mirror of
https://github.com/libssh2/libssh2.git
synced 2026-10-24 03:48:58 +03:00
9a0b40af73
If it improves consistency across builds and sources, prefer 'greater' or newer/later/+, prefer no 'v'/'version` prefix. Closes #1866
171 lines
4.6 KiB
Markdown
171 lines
4.6 KiB
Markdown
<!--
|
|
Copyright (C) The libssh2 project and its contributors.
|
|
|
|
SPDX-License-Identifier: BSD-3-Clause
|
|
-->
|
|
|
|
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 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<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`](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:
|
|
<https://cmake.org/cmake/help/v3.18/manual/cmake-packages.7.html>
|
|
|
|
* `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 <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.
|
|
|
|
```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 <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 "")
|
|
```
|