1# Installation Instructions
2
3**CAUTION**: ClamAV CMake support is experimental in this release and is not
4recommended for production systems!!!
5
6Please help us stabilize it so we can deprecate autotools and Visual Studio.
7
8_Known Issues / To-do:_
9
10- Support for building unit tests / feature tests and running with CTest
11  - A portion of this task will involve converting the shell scripts portions
12    to Python unit tests.
13- Build fuzz targets.
14- LLVM bytecode runtime support.
15  - Presently only the bytecode intepreter is supported. LLVM is preferable
16    because it is faster. This task also requires updating to use a modern
17    version of LLVM. Currently ClamAV is limited to LLVM 3.6.
18  - The built-in LLVM runtime is not supported in the CMake tooling with no
19    plans to add support. It will likely be removed when system-LLVM support
20    is updated.
21- Complete the MAINTAINER_MODE option to generate jsparse files with GPerf.
22
23- [Installation Instructions](#installation-instructions)
24  - [CMake Basics](#cmake-basics)
25    - [Basic Release build & system install](#basic-release-build--system-install)
26    - [Basic Debug build](#basic-debug-build)
27    - [Build and install to a specific install location (prefix)](#build-and-install-to-a-specific-install-location-prefix)
28    - [Build using Ninja](#build-using-ninja)
29    - [Build and run tests](#build-and-run-tests)
30  - [Custom CMake options](#custom-cmake-options)
31  - [Custom Library Paths](#custom-library-paths)
32    - [Example Build Commands](#example-build-commands)
33      - [Linux release build, install to system](#linux-release-build-install-to-system)
34      - [macOS debug build, custom OpenSSL path, build examples, local install](#macos-debug-build-custom-openssl-path-build-examples-local-install)
35      - [Windows Build](#windows-build)
36    - [External Depedencies](#external-depedencies)
37      - [libclamav dependencies](#libclamav-dependencies)
38      - [libfreshclam dependencies](#libfreshclam-dependencies)
39      - [Application dependencies](#application-dependencies)
40      - [Dependency build options](#dependency-build-options)
41        - [bzip2](#bzip2)
42        - [zlib](#zlib)
43        - [libxml2](#libxml2)
44        - [libpcre2](#libpcre2)
45        - [openssl (libcrypto, libssl)](#openssl-libcrypto-libssl)
46        - [libjson-c](#libjson-c)
47        - [libmspack](#libmspack)
48        - [iconv (POSIX-only)](#iconv-posix-only)
49        - [pthreads-win32 (Windows-only)](#pthreads-win32-windows-only)
50        - [llvm (optional, _see "Bytecode Runtime" section_)](#llvm-optional-see-bytecode-runtime-section)
51        - [libcurl](#libcurl)
52        - [ncurses or pdcurses, for clamdtop](#ncurses-or-pdcurses-for-clamdtop)
53        - [Bytecode Runtime](#bytecode-runtime)
54  - [Compilers and Options](#compilers-and-options)
55  - [Compiling For Multiple Architectures](#compiling-for-multiple-architectures)
56
57## CMake Basics
58
59Build requirements:
60
61- CMake 3.13+
62- A C-toolchain such as gcc, clang, or Microsoft Visual Studio.
63- Flex and Bison. On Windows, `choco install winflexbison`.
64
65_Important_: The following instructions assume that you have created a `build`
66subdirectory and that subsequent commands are performed from said directory,
67like so:
68
69```sh
70mkdir build && cd build
71```
72
73### Basic Release build & system install
74
75```sh
76cmake .. -DCMAKE_BUILD_TYPE="Release"
77cmake --build . --config Release
78sudo cmake --build . --config Release --target install
79```
80
81### Basic Debug build
82
83In CMake, "Debug" builds mean that symbols are compiled in.
84
85```sh
86cmake .. -DCMAKE_BUILD_TYPE="Debug"
87cmake --build . --config Debug
88```
89
90You will likely also wish to disable compiler/linker optimizations, which you
91can do like so, using our custom `OPTIMIZE` option:
92
93```sh
94cmake .. -DCMAKE_BUILD_TYPE="Debug" -DOPTIMIZE=OFF
95cmake --build . --config Debug
96```
97
98### Build and install to a specific install location (prefix)
99
100```sh
101cmake -DCMAKE_INSTALL_PREFIX:PATH=install ..
102cmake --build . --target install --config Release
103```
104
105### Build using Ninja
106
107This build uses Ninja (ninja-build) instead of Make. It's _really_ fast.
108
109```sh
110cmake .. -G Ninja
111cmake --build . --config Release
112```
113
114### Build and run tests
115
116_TODO_: We have not yet added unit test support for CMake.
117
118- `-V`: Verbose
119
120- `-C <config>`: Specify build configuration (i.e. Debug / Release), required
121                 for Windows builds
122
123```sh
124cmake ..
125cmake --build . --config Release
126ctest -C Release -V
127```
128
129## Custom CMake options
130
131The following CMake options can be selected by using `-D`. For example:
132
133```sh
134cmake .. -DENABLE_EXAMPLES
135cmake --build . --config Debug
136```
137
138- `APP_CONFIG_DIRECTORY`: App Config directory.
139
140  _Default: Windows: `{prefix}`, POSIX: `{prefix}/etc`_
141
142- `DATABASE_DIRECTORY`: Database directory.
143
144  _Default: Windows: `{prefix}/database`, POSIX: `{prefix}/share/clamav`_
145
146- `CLAMAV_USER`: ClamAV User (POSIX-only).
147
148  _Default: `clamav`_
149
150- `CLAMAV_GROUP`: ClamAV Group (POSIX-only).
151
152  _Default: `clamav`_
153
154- `MMAP_FOR_CROSSCOMPILING`: Force MMAP support for cross-compiling.
155
156  _Default: `OFF`_
157
158- `DISABLE_MPOOL`: Disable mpool support entirely.
159
160  _Default: `OFF`_
161
162- `BYTECODE_RUNTIME`: Bytecode Runtime, may be: `llvm`, `interpreter`, `none`.
163
164  _Default: `interpreter`_
165
166- `OPTIMIZE`: Allow compiler optimizations (eg. `-O3`). Set to `OFF` to disable
167  them (`-O0`).
168
169  _Default: `ON`_
170
171- `ENABLE_WERROR`: Compile time warnings will cause build failures (i.e.
172  `-Werror`)
173
174  _Default: `OFF`_
175
176- `ENABLE_ALL_THE_WARNINGS`: By default we use `-Wall -Wextra -Wformat-security`
177  for clamav libs and apps. This option enables a whole lot more.
178
179  _Default: `OFF`_
180
181- `ENABLE_DEBUG`: Turn on extra debug output.
182
183  _Default: `OFF`_
184
185- `ENABLE_FUZZ`: Build fuzz targets. Will enable `ENABLE_STATIC_LIB` for you.
186
187  _Default: `OFF`_
188
189- `ENABLE_EXTERNAL_MSPACK`: Use external mspack instead of internal libclammspack.
190
191  _Default: `OFF`_
192
193- `ENABLE_JSON_SHARED`: Prefer linking with libjson-c shared library instead of
194  static. Please set this to `OFF` if you're an application developer that uses
195  a different JSON library in your app, or if you provide libclamav to others.
196
197  _Default: `ON`_
198
199- `ENABLE_APP`: Build applications (clamscan, clamd, clamdscan, sigtool,
200  clambc, clamdtop, clamsubmit, clamconf).
201
202  _Default: `ON`_
203
204- `ENABLE_CLAMONACC`: (Linux-only) Build the clamonacc on-access scanning daemon.
205  Requires: `ENABLE_APP`
206
207  _Default: `ON`_
208
209- `ENABLE_MILTER`: (Posix-only) Build the clamav-milter mail filter daemon.
210  Requires: `ENABLE_APP`
211
212  _Default: `OFF`_
213
214- `ENABLE_UNRAR`: Build & install libclamunrar (UnRAR) and libclamunrar_iface.
215
216  _Default: `ON`_
217
218- `ENABLE_DOCS`: Generate man pages.
219
220  _Default: `OFF`_
221
222- `ENABLE_DOXYGEN`: Generate doxygen HTML documentation for clamav.h,
223  libfreshclam.h. Requires doxygen.
224
225  _Default: `OFF`_
226
227- `ENABLE_EXAMPLES`: Build examples.
228
229  _Default: `OFF`_
230
231- `ENABLE_LIBCLAMAV_ONLY`: Build libclamav only. Excludes libfreshclam too!
232
233  _Default: `OFF`_
234
235- `ENABLE_STATIC_LIB`: Build libclamav and/or libfreshclam static libraries.
236
237  _Default: `OFF`_
238
239- `ENABLE_SHARED_LIB`: Build libclamav and/or libfreshclam shared libraries.
240
241  _Default: `ON`_
242
243- `ENABLE_SYSTEMD`: Install systemd service files if systemd is found.
244
245  _Default: `ON`_
246
247- `MAINTAINER_MODE`: Generate Yara lexer and grammar C source with Flex & Bison.
248  TODO: Also generate JS parse source with Gperf.
249
250  _Default: `OFF`_
251
252- `SYSTEMD_UNIT_DIR`: Install systemd service files to a specific directory.
253  This will fail the build if systemd not found.
254
255  _Default: not set_
256
257## Custom Library Paths
258
259### Example Build Commands
260
261#### Linux release build, install to system
262
263This example sets the build system to Ninja instead of using Make, for speed.
264You may need to first use `apt`/`dnf`/`pkg` to install `ninja-build`
265
266```sh
267cmake .. -G Ninja \
268  -DCMAKE_BUILD_TYPE=Release \
269  -DENABLE_JSON_SHARED=OFF
270ninja
271sudo ninja install
272```
273
274#### macOS debug build, custom OpenSSL path, build examples, local install
275
276macOS builds use Homebrew to install `flex`, `bison`, and each of the library
277dependencies.
278
279Note that explicit paths for OpenSSL are requires so as to avoid using an older
280OpenSSL install provided by the operating system.
281
282This example also:
283
284- Build system to Ninja instead of using Make.
285  - You may need to first use `brew` to install `ninja`.
286- Sets build type to "Debug" and explicitly disables compiler optimizations.
287- Builds static libraries (and also shared libraries, which are on by default).
288- Builds the example programs, just to test them out.
289- Sets the install path (prefix) to ./install
290
291```sh
292cmake .. -G Ninja                                                              \
293  -DCMAKE_BUILD_TYPE=Debug                                                     \
294  -DOPTIMIZE=OFF                                                               \
295  -DENABLE_JSON_SHARED=OFF                                                     \
296  -DOPENSSL_ROOT_DIR=/usr/local/opt/openssl@1.1/                               \
297  -DOPENSSL_CRYPTO_LIBRARY=/usr/local/opt/openssl@1.1/lib/libcrypto.1.1.dylib  \
298  -DOPENSSL_SSL_LIBRARY=/usr/local/opt/openssl@1.1/lib/libssl.1.1.dylib        \
299  -DENABLE_STATIC_LIB=ON                                                       \
300  -DENABLE_EXAMPLES=ON                                                         \
301  -DCMAKE_INSTALL_PREFIX=install
302ninja
303ninja install
304```
305
306#### Windows Build
307
308Chocolatey (`choco`) is used to install `winflexbison` and `cmake`.
309Visual Studio 2015+ is required, 2017+ recommended.
310
311These instructions assume that `$env:CLAMAV_DEPENDENCIES` is set to your
312[Mussels](https://github.com/Cisco-Talos/Mussels) `install\x64` directory and
313that you've used Mussels to build the `clamav_deps` collection which will
314provide the required libraries.
315
316_Tip_: Instead of building manually, try using Mussels to automate your build!
317
318```ps1
319$env:CLAMAV_DEPENDENCIES="$env:userprofile\.mussels\install\x64"
320cmake ..  -G "Visual Studio 15 2017" -A x64 `
321    -DJSONC_INCLUDE_DIR="$env:CLAMAV_DEPENDENCIES\include\json-c"         `
322    -DJSONC_LIBRARY="$env:CLAMAV_DEPENDENCIES\lib\json-c.lib"             `
323    -DBZIP2_INCLUDE_DIR="$env:CLAMAV_DEPENDENCIES\include"                `
324    -DBZIP2_LIBRARY_RELEASE="$env:CLAMAV_DEPENDENCIES\lib\libbz2.lib"     `
325    -DCURL_INCLUDE_DIR="$env:CLAMAV_DEPENDENCIES\include"                 `
326    -DCURL_LIBRARY="$env:CLAMAV_DEPENDENCIES\lib\libcurl_imp.lib"         `
327    -DOPENSSL_ROOT_DIR="$env:CLAMAV_DEPENDENCIES"                         `
328    -DOPENSSL_INCLUDE_DIR="$env:CLAMAV_DEPENDENCIES\include"              `
329    -DOPENSSL_CRYPTO_LIBRARY="$env:CLAMAV_DEPENDENCIES\lib\libcrypto.lib" `
330    -DZLIB_LIBRARY="$env:CLAMAV_DEPENDENCIES\lib\libssl.lib"              `
331    -DLIBXML2_INCLUDE_DIR="$env:CLAMAV_DEPENDENCIES\include"              `
332    -DLIBXML2_LIBRARY="$env:CLAMAV_DEPENDENCIES\lib\libxml2.lib"          `
333    -DPCRE2_INCLUDE_DIR="$env:CLAMAV_DEPENDENCIES\include"                `
334    -DPCRE2_LIBRARY="$env:CLAMAV_DEPENDENCIES\lib\pcre2-8.lib"            `
335    -DCURSES_INCLUDE_DIR="$env:CLAMAV_DEPENDENCIES\include"               `
336    -DCURSES_LIBRARY="$env:CLAMAV_DEPENDENCIES\lib\pdcurses.lib"          `
337    -DPThreadW32_INCLUDE_DIR="$env:CLAMAV_DEPENDENCIES\include"           `
338    -DPThreadW32_LIBRARY="$env:CLAMAV_DEPENDENCIES\lib\pthreadVC2.lib"    `
339    -DZLIB_INCLUDE_DIR="$env:CLAMAV_DEPENDENCIES\include"                 `
340    -DZLIB_LIBRARY="$env:CLAMAV_DEPENDENCIES\lib\zlibstatic.lib"          `
341    -DCMAKE_INSTALL_PREFIX="install"
342cmake --build . --config Release --target install
343copy $env:CLAMAV_DEPENDENCIES\lib\* .\install
344```
345
346_Tip_: If you're having include-path issues, try building with detailed verbosity:
347
348```ps1
349cmake --build . --config Release --target install -- /verbosity:detailed
350```
351
352### External Depedencies
353
354The CMake tooling is good about finding installed dependencies on POSIX systems.
355
356_Important_: Linux users will want the "-dev" or "-devel" package variants
357which include C headers. For macOS, Homebrew doesn't separate the headers.
358
359#### libclamav dependencies
360
361App developers that only need libclamav can use the `-DENABLE_LIBCLAMAV_ONLY`
362option to bypass ClamAV app dependencies.
363
364libclamav requires these library dependencies:
365
366- bzip2
367- zlib
368- libxml2
369- libpcre2
370- openssl
371- libjson-c
372- iconv (POSIX-only, may be provided by system)
373- pthreads (or on Windows: pthreads-win32)
374- llvm (optional, _see [Bytecode Runtime](#bytecode-runtime))
375
376#### libfreshclam dependencies
377
378If you want libclamav _and_ libfreshclam for your app, then use the
379`-DENABLE_APP=OFF` option instead.
380
381libfreshclam adds these additional library dependencies:
382
383- libcurl
384
385#### Application dependencies
386
387For regular folk who want the ClamAV apps, you'll also need:
388
389- ncurses (or pdcurses), for clamdtop.
390- systemd, so clamd, freshclam, clamonacc may run as a systemd service (Linux).
391- libsystemd, so clamd will support the clamd.ctl socket (Linux).
392
393#### Dependency build options
394
395If you have custom install paths for the dependencies on your system or are
396on Windows, you may need to use the following options...
397
398##### bzip2
399
400```sh
401  -DBZIP2_INCLUDE_DIR="_filepath of bzip2 header directory_"
402  -DBZIP2_LIBRARIES="_filepath of bzip2 library_"
403```
404
405##### zlib
406
407```sh
408  -DZLIB_INCLUDE_DIR="_filepath of zlib header directory_"
409  -DZLIB_LIBRARY="_filepath of zlib library_"
410```
411
412##### libxml2
413
414```sh
415  -DLIBXML2_INCLUDE_DIR="_filepath of libxml2 header directory_"
416  -DLIBXML2_LIBRARY="_filepath of libxml2 library_"
417```
418
419##### libpcre2
420
421```sh
422  -DPCRE2_INCLUDE_DIR="_filepath of libpcre2 header directory_"
423  -DPCRE2_LIBRARY="_filepath of libcpre2 library_"
424```
425
426##### openssl (libcrypto, libssl)
427
428Hints to find openssl package:
429
430```sh
431  -DOPENSSL_ROOT_DIR="_path to openssl install root_"
432```
433
434```sh
435  -DOPENSSL_INCLUDE_DIR="_filepath of openssl header directory_"
436  -DOPENSSL_CRYPTO_LIBRARY="_filepath of libcrypto library_"
437  -DOPENSSL_SSL_LIBRARY="_filepath of libcrypto library_"
438```
439
440##### libjson-c
441
442Tip: You're strongly encouraged to link with the a static json-c library.
443
444```sh
445  -DJSONC_INCLUDE_DIR="_path to json-c header directory_"
446  -DJSONC_LIBRARY="_filepath of json-c library_"
447```
448
449##### libmspack
450
451These options only apply if you use the `-DENABLE_EXTERNAL_MSPACK=ON` option.
452
453```sh
454  -DMSPack_INCLUDE_DIR="_path to mspack header directory_"
455  -DMSPack_LIBRARY="_filepath of libmspack library_"
456```
457
458##### iconv (POSIX-only)
459
460On POSIX platforms, iconv might be part of the C library in which case you
461would not want to specify an external iconv library.
462
463```sh
464  -DIconv_INCLUDE_DIR="_path to iconv header directory_"
465  -DIconv_LIBRARY="_filepath of iconv library_"
466```
467
468##### pthreads-win32 (Windows-only)
469
470On POSIX platforms, pthread support is detected automatically.  On Windows, you
471need to specify the following:
472
473```sh
474  -DPThreadW32_INCLUDE_DIR="_path to pthread-win32 header directory_"
475  -DPThreadW32_LIBRARY="_filepath of pthread-win32 library_"
476```
477
478##### llvm (optional, _see "Bytecode Runtime" section_)
479
480```sh
481  -DBYTECODE_RUNTIME="llvm"
482  -DLLVM_ROOT_DIR="_path to llvm install root_" -DLLVM_FIND_VERSION="3.6.0"
483```
484
485##### libcurl
486
487```sh
488  -DCURL_INCLUDE_DIR="_path to curl header directory_"
489  -DCURL_LIBRARY="_filepath of curl library_"
490```
491
492##### ncurses or pdcurses, for clamdtop
493
494```sh
495  -DCURSES_INCLUDE_DIR="_path to curses header directory_"
496  -DCURSES_LIBRARY="_filepath of curses library_"
497```
498
499##### Bytecode Runtime
500
501Bytecode signatures are a type of executable plugin that provide extra
502detection capabilities.
503
504ClamAV has two bytecode runtimes:
505
506- *LLVM*: LLVM is the preferred runtime.
507
508  With LLVM, ClamAV JIT compiles bytecode signatures at database load time.
509  Bytecode signature execution is faster with LLVM.
510
511- *Interpreter*: The bytecode interpreter is an option on systems where a
512  a supported LLVM version is not available.
513
514  With the interpreter, signature database (re)loads are faster, but execution
515  time is slower.
516
517At the moment, the interpreter is the default runtime, while we work out
518compatibility issues with libLLVM. This default equates to:
519
520```sh
521cmake .. -DBYTECODE_RUNTIME="interpreter"
522```
523
524To build using LLVM instead of the intereter, use:
525
526```sh
527cmake .. \
528  -DBYTECODE_RUNTIME="llvm"       \
529  -DLLVM_ROOT_DIR="/opt/llvm/3.6" \
530  -DLLVM_FIND_VERSION="3.6.0"
531```
532
533To disable bytecode signature support entire, you may build with this option:
534
535```sh
536cmake .. -DBYTECODE_RUNTIME="none"
537```
538
539## Compilers and Options
540
541_TODO_: Describe how to customize compiler toolchain with CMake.
542
543## Compiling For Multiple Architectures
544
545_TODO_: Describe how to cross-compile with CMake.
546