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