License: see `COPYING` Source code: Web site source code: # Installation instructions with CMake To build libssh2 you need [CMake 3.18 or greater](https://cmake.org/download/) 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= .. ``` 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`](https://www.openssl-library.org/), [`Libgcrypt`](https://www.gnupg.org/), `WinCNG` (Windows Vista+), [`mbedTLS`](https://www.trustedfirmware.org/projects/mbed-tls/) or blank to use any library available. CMake attempts to locate the libraries automatically. For more information, visit: * `ENABLE_ZLIB_COMPRESSION=ON` Use [zlib](https://zlib.net/) 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` ## Using AWS-LC or BoringSSL You can also build against [AWS-LC](https://github.com/aws/aws-lc) or [BoringSSL](https://github.com/google/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 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=` 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. ```cmake 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](https://cmake.org/cmake/help/v3.18/manual/cmake-packages.7.html#package-registry) where `find_package` finds it. You can even combine the two steps using a so-called ['superbuild' project](https://www.kitware.com/main/wp-content/uploads/2016/01/kitware_quarterly1009.pdf) that downloads, builds and exports libssh2, and then builds your project: ```cmake include(ExternalProject) ExternalProject_Add( libssh2 URL URL_HASH SHA256= INSTALL_COMMAND "") ExternalProject_Add( MyProject DEPENDS libssh2 SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/src INSTALL_COMMAND "") ```