lib/libssh2
1
0
Fork 0
mirror of https://github.com/libssh2/libssh2.git synced 2026-10-24 03:48:58 +03:00
Code Activity

docs: markdownify

Browse Source 
Closes #1875
This commit is contained in:
Viktor Szakats
2026-04-23 17:06:51 +02:00
parent 4ea1cc6d27
commit 3a895e778b
11 changed files with 587 additions and 597 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
README
View File

@@ -15,5 +15,5 @@ Source code: https://github.com/libssh2/libssh2
Web site source code: https://github.com/libssh2/www
Installation instructions are in:
- docs/INSTALL_CMAKE for CMake
- docs/INSTALL_AUTOTOOLS for Autotools
- docs/INSTALL_AUTOTOOLS.md for autotools
- docs/INSTALL_CMAKE.md for CMake

2
README.md
View File

@@ -18,5 +18,5 @@ the revised BSD license.
[Web site source code](https://github.com/libssh2/www)
Installation instructions:
- [for autotools](docs/INSTALL_AUTOTOOLS.md)
- [for CMake](docs/INSTALL_CMAKE.md)
- [for autotools](docs/INSTALL_AUTOTOOLS)

1
REUSE.toml
View File

@@ -20,7 +20,6 @@ path = [
"RELEASE-NOTES",
"docs/AUTHORS",
"docs/HACKING-CRYPTO",
"docs/TODO",
"os400/README400",
"tests/key_*",
"tests/openssh_server/authorized_keys",

3
docs/BINDINGS.md
View File

@@ -4,8 +4,7 @@ Copyright (C) The libssh2 project and its contributors.
SPDX-License-Identifier: BSD-3-Clause
-->
libssh2 bindings
================
# libssh2 bindings
Creative people have written bindings or interfaces for various environments
and programming languages. Using one of these bindings allows you to take

4
docs/HACKING.md
View File

@@ -10,8 +10,8 @@ SPDX-License-Identifier: BSD-3-Clause
- spaces-only (no tabs)
- open braces on the if/for line:
```
if (banana) {
```c
if(banana) {
go_nuts();
}
```

316
docs/INSTALL_AUTOTOOLS
View File

@@ -1,316 +0,0 @@
Installation Instructions
*************************
Copyright (C) 1994, 1995, 1996, 1999, 2000, 2001, 2002, 2004, 2005 Free
Software Foundation, Inc.
This file is free documentation; the Free Software Foundation gives
unlimited permission to copy, distribute and modify it.
SPDX-License-Identifier: FSFULLR
When Building directly from Master
==================================
If you want to build directly from the git repository, you must first
generate the configure script and Makefile using autotools. Make
sure that autoconf, automake and libtool are installed on your system,
then execute:
autoreconf -fi
After executing this script, you can build the project as usual:
./configure
make
Basic Installation
==================
These are generic installation instructions.
The `configure' shell script attempts to guess correct values for
various system-dependent variables used during compilation. It uses
those values to create a `Makefile' in each directory of the package.
It may also create one or more `.h' files containing system-dependent
definitions. Finally, it creates a shell script `config.status' that
you can run in the future to recreate the current configuration, and a
file `config.log' containing compiler output (useful mainly for
debugging `configure').
It can also use an optional file (typically called `config.cache'
and enabled with `--cache-file=config.cache' or shortly `-C') that saves
the results of its tests to speed up reconfiguring. (Caching is
disabled by default to prevent problems with accidental use of stale
cache files.)
If you need to do unusual things to compile the package, please try
to figure out how `configure' could check whether to do them, and mail
diffs or instructions to the address given in the `README' so they can
be considered for the next release. If you are using the cache, and at
some point `config.cache' contains results you do not want to keep, you
may remove or edit it.
The file `configure.ac' (or `configure.in') is used to create
`configure' by a program called `autoconf'. You only need
`configure.ac' if you want to change it or regenerate `configure' using
a newer version of `autoconf'.
The simplest way to compile this package is:
1. `cd' to the directory containing the package's source code and type
`./configure' to configure the package for your system. If you are
using `csh' on an old version of System V, you might need to type
`sh ./configure' instead to prevent `csh' from trying to execute
`configure' itself.
Running `configure' takes awhile. While running, it prints some
messages telling which features it is checking for.
2. Type `make' to compile the package.
3. Optionally, type `make check' to run any self-tests that come with
the package.
4. Type `make install' to install the programs and any data files and
documentation.
5. You can remove the program binaries and object files from the
source code directory by typing `make clean'. To also remove the
files that `configure' created (so you can compile the package for
a different kind of computer), type `make distclean'. There is
also a `make maintainer-clean' target, but that is intended mainly
for the package's developers. If you use it, you may have to get
all sorts of other programs in order to regenerate files that came
with the distribution.
Compilers and Options
=====================
Some systems require unusual options for compilation or linking that the
`configure' script does not know about. Run `./configure --help' for
details on some of the pertinent environment variables.
You can give `configure' initial values for configuration parameters
by setting variables in the command line or in the environment. Here
is an example:
./configure CC=c89 CFLAGS=-O2 LIBS=-lposix
*Note Defining Variables::, for more details.
Compiling For Multiple Architectures
====================================
You can compile the package for more than one kind of computer at the
same time, by placing the object files for each architecture in their
own directory. To do this, you must use a version of `make' that
supports the `VPATH' variable, such as GNU `make'. `cd' to the
directory where you want the object files and executables to go and run
the `configure' script. `configure' automatically checks for the
source code in the directory that `configure' is in and in `..'.
If you have to use a `make' that does not support the `VPATH'
variable, you have to compile the package for one architecture at a
time in the source code directory. After you have installed the
package for one architecture, use `make distclean' before reconfiguring
for another architecture.
Installation Names
==================
By default, `make install' installs the package's commands under
`/usr/local/bin', include files under `/usr/local/include', etc. You
can specify an installation prefix other than `/usr/local' by giving
`configure' the option `--prefix=PREFIX'.
You can specify separate installation prefixes for
architecture-specific files and architecture-independent files. If you
pass the option `--exec-prefix=PREFIX' to `configure', the package uses
PREFIX as the prefix for installing programs and libraries.
Documentation and other data files still use the regular prefix.
In addition, if you use an unusual directory layout you can give
options like `--bindir=DIR' to specify different values for particular
kinds of files. Run `configure --help' for a list of the directories
you can set and what kinds of files go in them.
If the package supports it, you can cause programs to be installed
with an extra prefix or suffix on their names by giving `configure' the
option `--program-prefix=PREFIX' or `--program-suffix=SUFFIX'.
Optional Features
=================
Some packages pay attention to `--enable-FEATURE' options to
`configure', where FEATURE indicates an optional part of the package.
They may also pay attention to `--with-PACKAGE' options, where PACKAGE
is something like `gnu-as' or `x' (for the X Window System). The
`README' should mention any `--enable-' and `--with-' options that the
package recognizes.
For packages that use the X Window System, `configure' can usually
find the X include and library files automatically, but if it does not,
you can use the `configure' options `--x-includes=DIR' and
`--x-libraries=DIR' to specify their locations.
Specifying the System Type
==========================
There may be some features `configure' cannot figure out automatically,
but needs to determine by the type of machine the package will run on.
Usually, assuming the package is built to be run on the _same_
architectures, `configure' can figure that out, but if it prints a
message saying it cannot guess the machine type, give it the
`--build=TYPE' option. TYPE can either be a short name for the system
type, such as `sun4', or a canonical name which has the form:
CPU-COMPANY-SYSTEM
where SYSTEM can have one of these forms:
OS KERNEL-OS
See the file `config.sub' for the possible values of each field. If
`config.sub' is not included in this package, then this package does not
need to know the machine type.
If you are _building_ compiler tools for cross-compiling, you should
use the option `--target=TYPE' to select the type of system they will
produce code for.
If you want to _use_ a cross compiler, that generates code for a
platform different from the build platform, you should specify the
"host" platform (i.e., that on which the generated programs will
eventually be run) with `--host=TYPE'.
Sharing Defaults
================
If you want to set default values for `configure' scripts to share, you
can create a site shell script called `config.site' that gives default
values for variables like `CC', `cache_file', and `prefix'.
`configure' looks for `PREFIX/share/config.site' if it exists, then
`PREFIX/etc/config.site' if it exists. Or, you can set the
`CONFIG_SITE' environment variable to the location of the site script.
A warning: not all `configure' scripts look for a site script.
Defining Variables
==================
Variables not defined in a site shell script can be set in the
environment passed to `configure'. However, some packages may run
configure again during the build, and the customized values of these
variables may be lost. In order to avoid this problem, you should set
them in the `configure' command line, using `VAR=value'. For example:
./configure CC=/usr/local2/bin/gcc
causes the specified `gcc' to be used as the C compiler (unless it is
overridden in the site shell script). Here is a another example:
/bin/bash ./configure CONFIG_SHELL=/bin/bash
Here the `CONFIG_SHELL=/bin/bash' operand causes subsequent
configuration-related scripts to be executed by `/bin/bash'.
`configure' Invocation
======================
`configure' recognizes the following options to control how it operates.
`--help'
`-h'
Print a summary of the options to `configure', and exit.
`--version'
`-V'
Print the version of Autoconf used to generate the `configure'
script, and exit.
`--cache-file=FILE'
Enable the cache: use and save the results of the tests in FILE,
traditionally `config.cache'. FILE defaults to `/dev/null' to
disable caching.
`--config-cache'
`-C'
Alias for `--cache-file=config.cache'.
`--quiet'
`--silent'
`-q'
Do not print messages saying which checks are being made. To
suppress all normal output, redirect it to `/dev/null' (any error
messages will still be shown).
`--srcdir=DIR'
Look for the package's source code in directory DIR. Usually
`configure' can determine that directory automatically.
`configure' also accepts some other, not widely useful, options. Run
`configure --help' for more details.
More configure options
======================
Some ./configure options deserve additional comments:
* --with-libgcrypt
* --without-libgcrypt
* --with-libgcrypt-prefix=DIR
libssh2 can use the Libgcrypt library
(https://www.gnupg.org/) for cryptographic operations.
One of the cryptographic libraries is required.
Configure will attempt to locate Libgcrypt
automatically.
If your installation of Libgcrypt is in another
location, specify it using --with-libgcrypt-prefix.
* --with-openssl
* --without-openssl
* --with-libssl-prefix=[DIR]
libssh2 can use the OpenSSL library
(https://www.openssl-library.org/) for cryptographic operations.
One of the cryptographic libraries is required.
Configure will attempt to locate OpenSSL in the
default location.
If your installation of OpenSSL is in another
location, specify it using --with-libssl-prefix.
* --with-mbedtls
* --without-mbedtls
* --with-libmbedcrypto-prefix=[DIR]
libssh2 can use the mbedTLS library
(https://tls.mbed.org) for cryptographic operations.
One of the cryptographic libraries is required.
Configure will attempt to locate mbedTLS in the
default location.
If your installation of mbedTLS is in another
location, specify it using --with-libmbedcrypto-prefix.
* --with-libz
* --without-libz
* --with-libz-prefix=[DIR]
If present, libssh2 will attempt to use the zlib
(https://zlib.net/) for payload compression, however
zlib is not required.
If your installation of Libz is in another location,
specify it using --with-libz-prefix.
* --enable-debug
Will make the build use more pedantic and strict compiler
options as well as enable the libssh2_trace() function (for
showing debug traces).

304
docs/INSTALL_AUTOTOOLS.md Normal file
View File

@@ -0,0 +1,304 @@
# Installation Instructions
Copyright (C) 1994, 1995, 1996, 1999, 2000, 2001, 2002, 2004, 2005 Free
Software Foundation, Inc.
This file is free documentation; the Free Software Foundation gives unlimited
permission to copy, distribute and modify it.
SPDX-License-Identifier: FSFULLR
## When Building directly from Master
If you want to build directly from the git repository, you must first generate
the configure script and Makefile using autotools. Make sure that autoconf,
automake and libtool are installed on your system, then execute:
```sh
autoreconf -fi
```
After executing this script, you can build the project as usual:
```sh
./configure
make
```
## Basic Installation
These are generic installation instructions.
The `configure` shell script attempts to guess correct values for various
system-dependent variables used during compilation. It uses those values to
create a `Makefile` in each directory of the package. It may also create one
or more `.h` files containing system-dependent definitions. Finally, it
creates a shell script `config.status` that you can run in the future to
recreate the current configuration, and a file `config.log` containing
compiler output (useful mainly for debugging `configure`).
It can also use an optional file (typically called `config.cache` and enabled
with `--cache-file=config.cache` or shortly `-C`) that saves the results of
its tests to speed up reconfiguring. (Caching is disabled by default to
prevent problems with accidental use of stale cache files.)
If you need to do unusual things to compile the package, please try to figure
out how `configure` could check whether to do them, and mail diffs or
instructions to the address given in the `README` so they can be considered
for the next release. If you are using the cache, and at some point
`config.cache` contains results you do not want to keep, you may remove or
edit it.
The file `configure.ac` (or `configure.in`) is used to create `configure` by
a program called `autoconf`. You only need `configure.ac` if you want to change
it or regenerate `configure` using a newer version of `autoconf`.
The simplest way to compile this package is:
1. `cd` to the directory containing the package's source code and type
`./configure` to configure the package for your system. If you are using
`csh` on an old version of System V, you might need to type `sh ./configure`
instead to prevent `csh` from trying to execute `configure` itself.
Running `configure` takes awhile. While running, it prints some messages
telling which features it is checking for.
2. Type `make` to compile the package.
3. Optionally, type `make check` to run any self-tests that come with
the package.
4. Type `make install` to install the programs and any data files and
documentation.
5. You can remove the program binaries and object files from the source code
directory by typing `make clean`. To also remove the files that `configure`
created (so you can compile the package for a different kind of computer),
type `make distclean`. There is also a `make maintainer-clean` target, but
that is intended mainly for the package's developers. If you use it, you may
have to get all sorts of other programs in order to regenerate files that
came with the distribution.
## Compilers and Options
Some systems require unusual options for compilation or linking that the
`configure` script does not know about. Run `./configure --help` for details
on some of the pertinent environment variables.
You can give `configure` initial values for configuration parameters by
setting variables in the command line or in the environment. Here is an
example:
```
./configure CC=c89 CFLAGS=-O2 LIBS=-lposix
```
*Note Defining Variables::, for more details.
## Compiling For Multiple Architectures
You can compile the package for more than one kind of computer at the same
time, by placing the object files for each architecture in their own
directory. To do this, you must use a version of `make` that supports the
`VPATH` variable, such as GNU `make`. `cd` to the directory where you want the
object files and executables to go and run the `configure` script.
`configure` automatically checks for the source code in the directory that
`configure` is in and in `..`.
If you have to use a `make` that does not support the `VPATH` variable, you
have to compile the package for one architecture at a time in the source code
directory. After you have installed the package for one architecture, use
`make distclean` before reconfiguring for another architecture.
## Installation Names
By default, `make install` installs the package's commands under
`/usr/local/bin`, include files under `/usr/local/include`, etc. You can
specify an installation prefix other than `/usr/local` by giving `configure`
the option `--prefix=PREFIX`.
You can specify separate installation prefixes for architecture-specific files
and architecture-independent files. If you pass the option
`--exec-prefix=PREFIX` to `configure`, the package uses PREFIX as the prefix
for installing programs and libraries. Documentation and other data files
still use the regular prefix.
In addition, if you use an unusual directory layout you can give options like
`--bindir=DIR` to specify different values for particular kinds of files. Run
`configure --help` for a list of the directories you can set and what kinds of
files go in them.
If the package supports it, you can cause programs to be installed with an
extra prefix or suffix on their names by giving `configure` the option
`--program-prefix=PREFIX` or `--program-suffix=SUFFIX`.
## Optional Features
Some packages pay attention to `--enable-FEATURE` options to `configure`,
where FEATURE indicates an optional part of the package. They may also pay
attention to `--with-PACKAGE` options, where PACKAGE is something like
`gnu-as` or `x` (for the X Window System). The `README` should mention any
`--enable-` and `--with-` options that the package recognizes.
For packages that use the X Window System, `configure` can usually find the X
include and library files automatically, but if it does not, you can use the
`configure` options `--x-includes=DIR` and `--x-libraries=DIR` to specify
their locations.
## Specifying the System Type
There may be some features `configure` cannot figure out automatically, but
needs to determine by the type of machine the package will run on. Usually,
assuming the package is built to be run on the _same_ architectures,
`configure` can figure that out, but if it prints a message saying it cannot
guess the machine type, give it the `--build=TYPE` option. TYPE can either be
a short name for the system type, such as `sun4`, or a canonical name which
has the form:
```
CPU-COMPANY-SYSTEM
```
where SYSTEM can have one of these forms:
```
OS KERNEL-OS
```
See the file `config.sub` for the possible values of each field. If
`config.sub` is not included in this package, then this package does not need
to know the machine type.
If you are _building_ compiler tools for cross-compiling, you should use the
option `--target=TYPE` to select the type of system they will produce code
for.
If you want to _use_ a cross compiler, that generates code for a platform
different from the build platform, you should specify the "host" platform
(i.e., that on which the generated programs will eventually be run) with
`--host=TYPE`.
## Sharing Defaults
If you want to set default values for `configure` scripts to share, you can
create a site shell script called `config.site` that gives default values for
variables like `CC`, `cache_file`, and `prefix`. `configure` looks for
`PREFIX/share/config.site` if it exists, then `PREFIX/etc/config.site` if it
exists. Or, you can set the `CONFIG_SITE` environment variable to the location
of the site script. A warning: not all `configure` scripts look for a site
script.
## Defining Variables
Variables not defined in a site shell script can be set in the environment
passed to `configure`. However, some packages may run configure again during
the build, and the customized values of these variables may be lost. In order
to avoid this problem, you should set them in the `configure` command line,
using `VAR=value`. For example:
```sh
./configure CC=/usr/local2/bin/gcc
```
causes the specified `gcc` to be used as the C compiler (unless it is
overridden in the site shell script). Here is a another example:
```sh
/bin/bash ./configure CONFIG_SHELL=/bin/bash
```
Here the `CONFIG_SHELL=/bin/bash` operand causes subsequent
configuration-related scripts to be executed by `/bin/bash`.
## `configure` Invocation
`configure` recognizes the following options to control how it operates.
* `--help`, `-h`
Print a summary of the options to `configure`, and exit.
* `--version`, `-V`
Print the version of Autoconf used to generate the `configure` script, and
exit.
* `--cache-file=FILE`
Enable the cache: use and save the results of the tests in FILE,
traditionally `config.cache`. FILE defaults to `/dev/null` to disable
caching.
* `--config-cache`, `-C`
Alias for `--cache-file=config.cache`.
* `--quiet`, `--silent`, `-q`
Do not print messages saying which checks are being made. To suppress all
normal output, redirect it to `/dev/null` (any error messages will still be
shown).
* `--srcdir=DIR`
Look for the package's source code in directory DIR. Usually `configure`
can determine that directory automatically.
`configure` also accepts some other, not widely useful, options. Run
`configure --help` for more details.
## More configure options
Some `./configure` options deserve additional comments:
* `--with-libgcrypt`
* `--without-libgcrypt`
* `--with-libgcrypt-prefix=DIR`
libssh2 can use the [Libgcrypt](https://www.gnupg.org/) library for
cryptographic operations. One of the cryptographic libraries is required.
Configure will attempt to locate Libgcrypt automatically.
If your installation of Libgcrypt is in another location, specify it using
`--with-libgcrypt-prefix`.
* `--with-openssl`
* `--without-openssl`
* `--with-libssl-prefix=[DIR]`
libssh2 can use the [OpenSSL library](https://www.openssl-library.org/) for
cryptographic operations. One of the cryptographic libraries is required.
Configure will attempt to locate OpenSSL in the default location.
If your installation of OpenSSL is in another location, specify it using
`--with-libssl-prefix`.
* `--with-mbedtls`
* `--without-mbedtls`
* `--with-libmbedcrypto-prefix=[DIR]`
libssh2 can use the
[mbedTLS library](https://www.trustedfirmware.org/projects/mbed-tls/) for
cryptographic operations. One of the cryptographic libraries is required.
Configure will attempt to locate mbedTLS in the default location.
If your installation of mbedTLS is in another location, specify it using
`--with-libmbedcrypto-prefix`.
* `--with-libz`
* `--without-libz`
* `--with-libz-prefix=[DIR]`
If present, libssh2 will attempt to use the [zlib](https://zlib.net/) for
payload compression, however zlib is not required.
If your installation of Libz is in another location, specify it using
`--with-libz-prefix`.
* `--enable-debug`
Will make the build use more pedantic and strict compiler options as well
as enable the `libssh2_trace()` function (for showing debug traces).

178
docs/INSTALL_CMAKE.md
View File

@@ -4,46 +4,45 @@ Copyright (C) The libssh2 project and its contributors.
SPDX-License-Identifier: BSD-3-Clause
-->
License: see COPYING
License: see `COPYING`
Source code: https://github.com/libssh2/libssh2
Source code: <https://github.com/libssh2/libssh2>
Web site source code: https://github.com/libssh2/www
Web site source code: <https://github.com/libssh2/www>
Installation instructions are in docs/INSTALL
=======
To build libssh2 you will need CMake v3.18 or later [1] and one of the
following cryptography libraries:
# Installation instructions with CMake
To build libssh2 you need [CMake v3.18 or later](https://cmake.org/download/)
and one of the following cryptography libraries:
* OpenSSL
* wolfSSL
* Libgcrypt
* WinCNG
* mbedTLS
* OpenSSL
* WinCNG
* wolfSSL
Getting started
---------------
## 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:
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
cmake -B bld
cmake --build bld
```
libssh2 will be built as a static library and will use any
cryptography library available. The library binary will be put in
`bld/src`, with the examples in `bld/example` and the tests in
`bld/tests`.
libssh2 will be built as a static library and will use any cryptography
library available. The library binary will be put in `bld/src`, with the
examples in `bld/example` and the tests in `bld/tests`.
Customising the build
---------------------
## Customising the build
You might want to customise the build options. You can pass the options
You might want to customise the build options. You can pass the options
to CMake on the command line:
cmake -D<option>=<value> ..
```
cmake -D<option>=<value> ..
```
The following options are available:
@@ -59,23 +58,24 @@ The following options are available:
* `BUILD_SHARED_LIBS=OFF`
Determines whether to build a libssh2 shared library (.dll/.so).
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.
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 will attempt to locate the libraries automatically. See [2]
for more information.
CMake will attempt 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.
Use [zlib](https://zlib.net/) for payload compression.
Can be `ON` or `OFF`. Default: `OFF`
* `ENABLE_DEBUG_LOGGING=ON`
@@ -88,90 +88,88 @@ The following options are available:
Disable secure zero memory before freeing it (not recommended).
Can be `ON` or `OFF`. Default: `ON`
Using BoringSSL or AWS-LC
-------------------------
You can also build against [BoringSSL](https://github.com/google/boringssl)
or [AWS-LC](https://github.com/aws/aws-lc). Specify `CRYPTO_BACKEND=OpenSSL`, then indicate
the installation directory of the cryptography library using `OPENSSL_ROOT_DIR=`
## Using BoringSSL or AWS-LC
Build tools
-----------
You can also build against [BoringSSL](https://github.com/google/boringssl) or
[AWS-LC](https://github.com/aws/aws-lc). 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 .
```
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.
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
-----
## Tests
To test the build, run the appropriate test target for your build
system. For example:
To test the build, run the appropriate test target for your build system. For
example:
```
cmake --build . --target test
cmake --build . --target test
```
or
```
cmake --build . --target RUN_TESTS
cmake --build . --target RUN_TESTS
```
How do I use libssh2 in my project if my project does not use CMake?
-------------------------------------------------------------------
## 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
cmake <libssh2 source location>
cmake --build .
cmake --build . --target install
```
or
```
cmake --build . --target INSTALL
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.
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?
----------------------------------------------------------
## 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 will find libssh2 on your system, set up the necessary paths and
link the library with your binary.
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 will find
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)
```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 will export its location to the user
package registry [3] where `find_package` will find it.
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 will export its location to the user
[package registry](https://cmake.org/cmake/help/v3.18/manual/cmake-packages.7.html#package-registry)
where `find_package` will find it.
You can even combine the two steps using a so-called 'superbuild'
project [4] that downloads, builds and exports libssh2, and then
builds your project:
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:
include(ExternalProject)
```cmake
include(ExternalProject)
ExternalProject_Add(
libssh2
URL <libssh2 download location>
URL_HASH SHA256=<libssh2 archive SHA256>
INSTALL_COMMAND "")
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 "")
[1] https://cmake.org/download/
[2] https://cmake.org/cmake/help/v3.18/manual/cmake-packages.7.html
[3] https://cmake.org/cmake/help/v3.18/manual/cmake-packages.7.html#package-registry
[4] https://www.kitware.com/main/wp-content/uploads/2016/01/kitware_quarterly1009.pdf
ExternalProject_Add(
MyProject DEPENDS libssh2
SOURCE_DIR ${CMAKE_CURRENT_SOURCE_DIR}/src
INSTALL_COMMAND "")
```

2
docs/Makefile.am
View File

@@ -17,5 +17,5 @@ SUFFIXES = .3 .md
endif
EXTRA_DIST = $(MANPAGES) template.md cd2nroff AUTHORS BINDINGS.md HACKING.md \
HACKING-CRYPTO INSTALL_AUTOTOOLS INSTALL_CMAKE.md SECURITY.md TODO \
HACKING-CRYPTO INSTALL_AUTOTOOLS.md INSTALL_CMAKE.md SECURITY.md TODO.md \
CMakeLists.txt

182
docs/TODO
View File

@@ -1,182 +0,0 @@
Things TODO
===========
* Fix -Wsign-conversion warnings in src
* Fix the numerous malloc+copy operations for sending data, see "Buffering
Improvements" below for details
* make sure the windowing code adapts better to slow situations so that it
does not then use as much memory as today. Possibly by an app-controllable
"Window mode"?
* Decrease the number of mallocs. Everywhere. Will get easier once the
buffering improvements have been done.
* Use SO_NOSIGPIPE for Mac OS/BSD systems where MSG_NOSIGNAL does not
exist/work
* Extend the test suite to actually test lots of aspects of libssh2
* Update public API to drop casts added to fix compiler warnings
* Expose error messages sent by the server
* select() is troublesome with libssh2 when using multiple channels over
the same session. See "New Transport API" below for more details.
* for obsolete/weak/insecure algorithms: either stop enabling them by default
at build-time, or delete support for them completely.
At next SONAME bump
===================
* stop using #defined macros as part of the official API. The macros should
either be turned into real functions or discarded from the API.
* delete or deprecate libssh2_session_callback_set()
* bump length arguments in callback functions to size_t/ssize_t
* remove the following functions from the API/ABI
libssh2_base64_decode()
libssh2_session_flag()
libssh2_channel_handle_extended_data()
libssh2_channel_receive_window_adjust()
libssh2_poll()
libssh2_poll_channel_read()
libssh2_scp_send()
libssh2_scp_send_ex()
libssh2_session_startup() (libssh2_session_handshake() is the replacement)
libssh2_banner_set() (libssh2_session_banner_set() is the replacement)
* Rename a few function:
libssh2_hostkey_hash => libssh2_session_hostkey_hash
libssh2_banner_set => libssh2_session_banner_set
* change 'int' to 'libssh2_socket_t' in the public API for sockets.
* Use 'size_t' for string lengths in all functions.
* Add a comment field to struct libssh2_knownhost.
* remove the existing libssh2_knownhost_add() function and rename
libssh2_knownhost_addc to become the new libssh2_knownhost_add instead
* remove the existing libssh2_scp_send_ex() function and rename
libssh2_scp_send64 to become the new libssh2_scp_send instead.
* remove the existing libssh2_knownhost_check() function and rename
libssh2_knownhost_checkp() to become the new libssh2_knownhost_check instead
Buffering Improvements
======================
transport_write
- If this function gets called with a total packet size that is larger than
32K, it should create more than one SSH packet so that it keeps the largest
one below 32K
sftp_write
- should not copy/allocate anything for the data, only create a header chunk
and pass on the payload data to channel_write "pointed to"
New Transport API
=================
THE PROBLEM
The problem in a nutshell is that when an application opens up multiple
channels over a single session, those are all using the same socket. If the
application is then using select() to wait for traffic (like any sensible app
does) and wants to act on the data when select() tells there is something to
for example read, what does an application do?
With our current API, you have to loop over all the channels and read from
them to see if they have data. This effectively makes blocking reads
impossible. If the app has many channels in a setup like this, it even becomes
slow. (The original API had the libssh2_poll_channel_read() and libssh2_poll()
to somewhat overcome this hurdle, but they too have pretty much the same
problems plus a few others.)
Traffic in the other direction is similarly limited: the app has to try
sending to all channels, even though some of them may very well not accept any
data at that point.
A SOLUTION
I suggest we introduce two new helper functions:
libssh2_transport_read()
- Read "a bunch" of data from the given socket and returns information to the
app about what channels that are now readable (ie they will not block when
read from). The function can be called over and over and it will repeatedly
return info about what channels that are readable at that moment.
libssh2_transport_write()
- Returns information about what channels that are writable, in the sense
that they have windows set from the remote side that allows data to get
sent. Writing to one of those channels will not block. Of course, the
underlying socket may only accept a certain amount of data, so at the first
short return, nothing more should be attempted to get sent until select()
(or equivalent) has been used on the master socket again.
I have not yet figured out a sensible API for how these functions should return
that info, but if we agree on the general principles I guess we can work that
out.
VOLUNTARY
I wanted to mention that these two helper functions would not be mandatory
in any way. They would just be there for those who want them, and existing
programs can remain using the old functions only if they prefer to.
New SFTP API
============
PURPOSE
Provide API functions that explicitly tells at once that a (full) SFTP file
transfer is wanted, to allow libssh2 to leverage on that knowledge to speed
up things internally. It can for example do read ahead, buffer writes (merge
small writes into larger chunks), better tune the SSH window and more. This
sort of API is already provided for SCP transfers.
API
New functions:
LIBSSH2_SFTP_HANDLE *libssh2_sftp_send(SFTP_SESSION *sftp,
libssh2_uint64_t filesize,
char *remote_path,
size_t remote_path_len,
long mode);
Tell libssh2 that a local file with a given size is about to get sent to
the SFTP server.
LIBSSH2_SFTP_HANDLE *libssh2_sftp_recv();
Tell libssh2 that a remote file is requested to get downloaded from the SFTP
server.
Only the setup of the file transfer is different from an application's point
of view. Depending on direction of the transfer(s), the following already
existing functions should then be used until the transfer is complete:
libssh2_sftp_read()
libssh2_sftp_write()
HOW TO USE
1. Setup the transfer using one of the two new functions.
2. Loop through the reading or writing of data.
3. Cleanup the transfer

188
docs/TODO.md Normal file
View File

@@ -0,0 +1,188 @@
<!--
Copyright (C) The libssh2 project and its contributors.
SPDX-License-Identifier: BSD-3-Clause
-->
# Things TODO
* Fix `-Wsign-conversion` warnings in src.
* Fix the numerous malloc+copy operations for sending data, see "Buffering
Improvements" below for details.
* make sure the windowing code adapts better to slow situations so that it
does not then use as much memory as today. Possibly by an app-controllable
"Window mode"?
* Decrease the number of mallocs. Everywhere. Will get easier once the
buffering improvements have been done.
* Use `SO_NOSIGPIPE` for macOS/BSD systems where `MSG_NOSIGNAL` does not
exist/work.
* Extend the test suite to actually test lots of aspects of libssh2.
* Update public API to drop casts added to fix compiler warnings.
* Expose error messages sent by the server.
* `select()` is troublesome with libssh2 when using multiple channels over
the same session. See "New Transport API" below for more details.
* for obsolete/weak/insecure algorithms: either stop enabling them by default
at build-time, or delete support for them completely.
## At next SONAME bump
* stop using #defined macros as part of the official API. The macros should
either be turned into real functions or discarded from the API.
* delete or deprecate `libssh2_session_callback_set()`
* bump length arguments in callback functions to `size_t`/`ssize_t`
* remove the following functions from the API/ABI
```
libssh2_base64_decode()
libssh2_session_flag()
libssh2_channel_handle_extended_data()
libssh2_channel_receive_window_adjust()
libssh2_poll()
libssh2_poll_channel_read()
libssh2_scp_send()
libssh2_scp_send_ex()
libssh2_session_startup() (libssh2_session_handshake() is the replacement)
libssh2_banner_set() (libssh2_session_banner_set() is the replacement)
```
* Rename a few function:
```
libssh2_hostkey_hash => libssh2_session_hostkey_hash
libssh2_banner_set => libssh2_session_banner_set
```
* change `int` to `libssh2_socket_t` in the public API for sockets.
* Use `size_t` for string lengths in all functions.
* Add a comment field to `struct libssh2_knownhost`.
* remove the existing `libssh2_knownhost_add()` function and rename
libssh2_knownhost_addc to become the new `libssh2_knownhost_add` instead.
* remove the existing `libssh2_scp_send_ex()` function and rename
`libssh2_scp_send64` to become the new `libssh2_scp_send` instead.
* remove the existing `libssh2_knownhost_check()` function and rename
`libssh2_knownhost_checkp()` to become the new `libssh2_knownhost_check`
instead.
## Buffering Improvements
* `transport_write`
If this function gets called with a total packet size that is larger than
32K, it should create more than one SSH packet so that it keeps the largest
one below 32K.
* `sftp_write`
Should not copy/allocate anything for the data, only create a header chunk
and pass on the payload data to channel_write "pointed to".
## New Transport API
THE PROBLEM
The problem in a nutshell is that when an application opens up multiple
channels over a single session, those are all using the same socket. If the
application is then using `select()` to wait for traffic (like any sensible app
does) and wants to act on the data when `select()` tells there is something to
for example read, what does an application do?
With our current API, you have to loop over all the channels and read from
them to see if they have data. This effectively makes blocking reads
impossible. If the app has many channels in a setup like this, it even becomes
slow. (The original API had the `libssh2_poll_channel_read()` and
`libssh2_poll()` to somewhat overcome this hurdle, but they too have pretty
much the same problems plus a few others.)
Traffic in the other direction is similarly limited: the app has to try
sending to all channels, even though some of them may very well not accept any
data at that point.
A SOLUTION
I suggest we introduce two new helper functions:
- `libssh2_transport_read()`
Read "a bunch" of data from the given socket and returns information to the
app about what channels that are now readable (ie they will not block when
read from). The function can be called over and over and it will repeatedly
return info about what channels that are readable at that moment.
- `libssh2_transport_write()`
Returns information about what channels that are writable, in the sense
that they have windows set from the remote side that allows data to get
sent. Writing to one of those channels will not block. Of course, the
underlying socket may only accept a certain amount of data, so at the first
short return, nothing more should be attempted to get sent until `select()`
(or equivalent) has been used on the master socket again.
I have not yet figured out a sensible API for how these functions should return
that info, but if we agree on the general principles I guess we can work that
out.
VOLUNTARY
I wanted to mention that these two helper functions would not be mandatory in
any way. They would just be there for those who want them, and existing
programs can remain using the old functions only if they prefer to.
## New SFTP API
PURPOSE
Provide API functions that explicitly tells at once that a (full) SFTP file
transfer is wanted, to allow libssh2 to leverage on that knowledge to speed
up things internally. It can for example do read ahead, buffer writes (merge
small writes into larger chunks), better tune the SSH window and more. This
sort of API is already provided for SCP transfers.
API
New functions:
```c
LIBSSH2_SFTP_HANDLE *libssh2_sftp_send(SFTP_SESSION *sftp,
libssh2_uint64_t filesize,
char *remote_path,
size_t remote_path_len,
long mode);
```
Tell libssh2 that a local file with a given size is about to get sent to
the SFTP server.
```c
LIBSSH2_SFTP_HANDLE *libssh2_sftp_recv();
```
Tell libssh2 that a remote file is requested to get downloaded from the SFTP
server.
Only the setup of the file transfer is different from an application's point
of view. Depending on direction of the transfer(s), the following already
existing functions should then be used until the transfer is complete:
- `libssh2_sftp_read()`
- `libssh2_sftp_write()`
HOW TO USE
1. Setup the transfer using one of the two new functions.
2. Loop through the reading or writing of data.
3. Cleanup the transfer