libssh2/docs/INSTALL-CMAKE.md

License: see COPYING

Source code: https://github.com/libssh2/libssh2

Web site source code: https://github.com/libssh2/www

Installation instructions with CMake

To build libssh2 you need CMake v3.18 or later and one of the following cryptography libraries:

• Libgcrypt
• mbedTLS
• OpenSSL
• WinCNG
• wolfSSL

Getting started

If you are happy with the default options, make a new build directory, change to it, configure the build environment and build the project:

cmake -B bld
cmake --build bld

libssh2 is built as a static library and uses any cryptography library available. The library binary is put in bld/src, with the examples in bld/example and the tests in bld/tests.

Customising the build

You might want to customise the build options. You can pass the options to CMake on the command line:

cmake -D<option>=<value> ..

The following options are available:

• LINT=ON

  Enables running the source code linter when building. Can be ON or OFF. Default: OFF

• BUILD_STATIC_LIBS=OFF

  Determines whether to build a libssh2 static library. Can be ON or OFF. Default: ON

• BUILD_SHARED_LIBS=OFF

  Determines whether to build a libssh2 shared library (.dll/.so). Can be ON or OFF. Default: ON

• CRYPTO_BACKEND=

  Chooses a specific cryptography library to use for cryptographic operations. Can be OpenSSL, Libgcrypt, WinCNG (Windows Vista+), mbedTLS or blank to use any library available.

  CMake attempts to locate the libraries automatically. For more information, visit: https://cmake.org/cmake/help/v3.18/manual/cmake-packages.7.html

• ENABLE_ZLIB_COMPRESSION=ON

  Use zlib for payload compression. Can be ON or OFF. Default: OFF

• ENABLE_DEBUG_LOGGING=ON

  Enable the libssh2_trace() function for showing debug traces. Can be ON or OFF. Default: OFF in Release, ON in Debug

• CLEAR_MEMORY=OFF

  Disable secure zero memory before freeing it (not recommended). Can be ON or OFF. Default: ON

Using AWS-LC or BoringSSL

You can also build against AWS-LC or BoringSSL. Specify CRYPTO_BACKEND=OpenSSL, then indicate the installation directory of the cryptography library using OPENSSL_ROOT_DIR=

Build tools

The previous examples used CMake to start the build using:

cmake --build .

Alternatively, once CMake has configured your project, you can use your own build tool, e.g GNU make, Visual Studio, etc., from that point onwards.

Tests

To test the build, run the appropriate test target for your build system. For example:

cmake --build . --target test

or

cmake --build . --target RUN_TESTS

How do I use libssh2 in my project if my project does not use CMake?

If you are not using CMake for your own project, install libssh2

cmake <libssh2 source location>
cmake --build .
cmake --build . --target install

or

cmake --build . --target INSTALL

and then specify the install location to your project in the normal way for your build environment. If you do not like the default install location, add -DCMAKE_INSTALL_PREFIX=<chosen prefix> when initially configuring the project.

How can I use libssh2 in my project if it also uses CMake?

If your own project also uses CMake, you do not need to worry about setting it up with libssh2's location. Add the following lines and CMake finds libssh2 on your system, set up the necessary paths and link the library with your binary.

find_package(libssh2 REQUIRED CONFIG)
target_link_libraries(my_project_target libssh2::libssh2)

You still have to make libssh2 available on your system first. You can install it in the traditional way shown above, but you do not have to. Instead you can build it, which exports its location to the user package registry where find_package finds it.

You can even combine the two steps using a so-called 'superbuild' project that downloads, builds and exports libssh2, and then builds your project:

include(ExternalProject)

ExternalProject_Add(
    libssh2
    URL <libssh2 download location>
    URL_HASH SHA256=<libssh2 archive SHA256>
    INSTALL_COMMAND "")

ExternalProject_Add(
    MyProject DEPENDS libssh2
    SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/src
    INSTALL_COMMAND "")