Debian Codegraph @

docs/README.building

raw
1
2 More documentation might be found at https://github.com/FreeRDP/FreeRDP/wiki/Compilation
3
4 FreeRDP has a few dependencies that are required for proper operation:
5
6 1. SSL (required)
7
8 RDP requires a secure tunnel and utilizes TLS for this. We do not implement this
9 ourselves but reuse existing libraries:
10
11 We support
12
13 * OpenSSL our main development SSL library (-DWITH_OPENSSL=ON, default)
14 * LibreSSL (supported by community, -DWITH_OPENSSL=ON, drop in replacement)
15 * MBedTLS (supported by community, -DWITH_OPENSSL=OFF -DWITH_MBEDTLS=ON)
16
17 optionally there are some algorithms that can be shipped with FreeRDP itself if the SSL library deprecated them:
18 * -DWITH_INTERNAL_MD4=ON
19 * -DWITH_INTERNAL_MD5=ON
20 * -DWITH_INTERNAL_RC4=ON
21
22 2. Kerberos (optional, disable with -DWITH_KRB5=OFF)
23
24 Authentication to many services requires kerberos (especially if smartcards are in use)
25
26 We support:
27
28 * MIT
29 * Heimdal
30
31 3. JSON (optional, disable with -DWITH_JSON_DISABLED=ON)
32
33 Azure logon requires HTTP/JSON messages to be parsed.
34
35 We support:
36
37 * cJSON
38 * json-c
39
40 4. H264
41
42 RDP GFX modes (anything newer Windows 8.1 / Server 2012) supports a graphics mode based
43 on the H264 codec
44
45 We support
46
47 * OpenH264 (enable with -DWITH_OPENH264=ON)
48 * FFMPEG (x264 or OpenH264, enable with -DWITH_FFMPEG=ON)
49
50 There are some platform specific implementations too (e.g. mediacodec on android) but these
51 two are the options that are always required.
52
53 5. Graphics scaling support (optional, required for HighDPI support)
54
55 High DPI support and smart-sizing option require bitmaps to be scaled by the client.
56
57 We support
58
59 * Swscale (enable with -DWITH_SWSCALE=ON)
60 * Cairo (enable with -DWITH_CAIRO=ON)
61
62 6. Audio encoders/decoders (optional, hightly recommended though)
63
64 Sound and Microphone options allow transmission of data in compressed formats.
65 The most widely supported formats are uncompressed PCM (all systems support that)
66 and compressed AAC (windows 8 or newer). Some other codecs are supported as well (GSM)
67 but do not provide the same quality as the afore mentioned ones.
68
69 We support
70
71 * FAAC / FAAD2 / soxr (encoder/decoder/resampling)
72 * GSM (older low bandwidth codec, -DWITH_GSM=ON)
73 * FFMPEG (-DWITH_DSP_FFMPEG)
74 * SOXR (optional, resampling library, enable with -DWITH_SOX!=ON)
75
76 to enable some experimental codecs (mainly AAC encoding) add -DWITH_DSP_EXPERIMENTAL=ON
77
78 7. Smartcard (optional)
79
80 To utilize smartcards for authentication/redirection
81
82 We support
83
84 * PCSC (disable with -DWITH_PCSC=OFF)
85 * pkcs11 (disable with -DWITH_PKCS11=OFF)
86
87 PCSC is required for smartcard redirection, pkcs11 for NLA smartcard logon support
88
89 8. Unicode (required, use -DWITH_UNICODE_BUILTIN=ON to utilize custom char16 <--> utf8 conversion routines)
90
91 Most of the protocol preferably uses UCS-2/UTF16 for strings. To convert to/from UTF-8 a
92 unicode support library is required:
93
94 * Windows natively supports these (well, it is a microsoft protocol after all ;))
95 * ICU on linux/unix and android
96 * On Apple (iOS/Mac) we use native NSString unicode conversion routines
97
98 9. USB redirection (optional, disable with -DCHANNEL_URBDRC=OFF)
99
100 The protocol has an extension (channel) to allow low level USB redirection
101
102 We support
103
104 * libusb 1
105
106 10. Platform support (mainly linux, for others the platform SDK is usually enough)
107
108 * SDL2 for the SDL client (all platforms, disable with -DWITH_CLIENT_SDL=OFF)
109 * CUPS (linux/apple) for printing support (disable with -DWITH_CUPS=OFF)
110 * libsystemd (linux) for journald logging support (disable with -DWITH_SYSTEMD=OFF)
111 * PAM headers/libraries (server side authentication)
112 * FUSE for file clipboard support (linux/mac os, disable with -DWITH_FUSE=OFF)
113 * Wayland for wlfreerdp (disable with -DWITH_WAYLAND=OFF)
114 * X11 development headers for X11 client (disable with -DWITH_X11=OFF)
115 * ALSA development headers/libraries (disable with -DWITH_ALSA=OFF)
116 * PULSE development headers/libraries (disable with -DWITH_PULSE=OFF)
117 * OSS development headers/libraries (disable with -DWITH_OSS=OFF)
118
119 11. WebAuthn / FIDO2 redirection (optional, disable with -DCHANNEL_RDPEWA=OFF)
120
121 The [MS-RDPEWA] WebAuthn Virtual Channel Extension allows forwarding WebAuthn/FIDO2
122 authenticator requests from the RDP server to the client's local security keys.
123 This enables passwordless authentication (e.g. passkeys) and two-factor authentication
124 inside the remote session using hardware security keys plugged into the client machine.
125
126 Enabled automatically when the required libraries are found. Requires:
127
128 * libcbor (CBOR encoding/decoding)
129 * libfido2 (FIDO2/CTAP2 authenticator communication)
130
131 On Debian/Ubuntu: apt install libcbor-dev libfido2-dev
132 On Fedora: dnf install libcbor-devel libfido2-devel
133
134 The channel is activated via the "redirectwebauthn" .rdp file setting
135 (FreeRDP_RedirectWebAuthN).
136
137 12. Server support
138
139 FreeRDP does provide server side RDP protocol implementation as well.
140 These are used by the RDP proxy (disable with -DWITH_PROXY=OFF) as well as shadow server (disable with -DWITH_SHADOW=OFF)
141
142 there are some (incomplete) platform implementations (enable with -DWITH_PLATFORM_SERVER=ON) which compile but do not provide anything useful yet.
143
144 13. Samples
145
146 There are a client and server sample provided. (disable with -DWITH_SAMPLE=OFF)
147
148 14. Tools (optional)
149
150 a couple of helper utilities are build alongside the client and server executables and libraries. These are mostly for handling certificates and NTLM hashes.
151 disable with -DWITH_WINPR_TOOLS=OFF
152
153 15. Building recommendations
154
155 * Use Ninja to speed up your builds
156 * For release builds add -DCMAKE_BUILD_TYPE=Release (or RelWithDebInfo for less optimized but with debug symbols)
157 * -DWITH_VERBOSE_WINPR_ASSERT=OFF reduces the size of the build considerably but removes lots
158 of sanity checks in code. Recommended for stable builds, for builds not from stable releases
159 it is recommended to keep -DWITH_VERBOSE_WINPR_ASSERT=ON to have useful information on crashes.
160
161 16. Example build instructions:
162
163 Assume we have the source checked out to /tmp/freerdp/src and we want to install to /tmp/freerdp/install:
164 (on windows this needs to be called from a visual studio command prompt or a cmd that has run vcvarsall.bat, paths obviously need to be adjusted)
165
166 cmake -GNinja -DCMAKE_BUILD_TYPE=Release -DWITH_VERBOSE_WINPR_ASSERT=OFF -DCMAKE_PREFIX_PATH=/tmp/freerdp/install -B /tmp/freerdp/build -S /tmp/freerdp/src
167 cmake --build /tmp/freerdp/build --target install
168
169 17. Useful tips:
170
171 * there is ccmake (linux/mac os) that is a curses ui to show a current CMakeCache.txt build configuration. There it is easy to check/change variables
172 * CMake supports preload files (see ci/ subfolder in repo) that allows creating a (custom) build configuration that can then be applied with cmake -C<preload file>