diff options
Diffstat (limited to 'README.md')
| -rw-r--r-- | README.md | 116 |
1 files changed, 62 insertions, 54 deletions
@@ -2,17 +2,26 @@ [](https://travis-ci.org/sfackler/rust-openssl) -[Documentation](https://sfackler.github.io/rust-openssl/doc/v0.8.3/openssl). +[Documentation](https://sfackler.github.io/rust-openssl/doc/v0.9.0/openssl). + +## Warning + +This README does not correspond to rust-openssl 0.7.x. See +[here](https://github.com/sfackler/rust-openssl/blob/b8fb29db5c246175a096260eacca38180cd77dd0/README.md) +for that README. ## Building -rust-openssl depends on both the OpenSSL runtime libraries and headers. +rust-openssl depends on the OpenSSL runtime libraries version 1.0.1 or above. +Currently the libraries need to be present in the build environment before this +crate is compiled, and some instructions of how to do this are in the sections +below. ### Linux -On Linux, you can install OpenSSL via your package manager. The headers are -sometimes provided in a separate package than the runtime libraries - look for -something like `openssl-devel` or `libssl-dev`. +On Linux, you can typically install OpenSSL via your package manager. The +headers are sometimes provided in a separate package than the runtime libraries +- look for something like `openssl-devel` or `libssl-dev`. ```bash # On Ubuntu @@ -23,79 +32,78 @@ sudo pacman -S openssl sudo dnf install openssl-devel ``` +If installation via a package manager is not possible, or if you're cross +compiling to a separate target, you'll typically need to compile OpenSSL from +source. That can normally be done with: + +``` +curl -O https://www.openssl.org/source/openssl-1.1.0b.tar.gz +tar xf openssl-1.1.0b.tar.gz +cd openssl-1.1.0b +export CC=... +./Configure --prefix=... linux-x86_64 -fPIC +make -j$(nproc) +make install +``` + ### OSX -OpenSSL 0.9.8 is preinstalled on OSX. Some features are only available when -linking against OpenSSL 1.0.0 or greater; see below on how to point -rust-openssl to a separate installation. OSX releases starting at 10.11, "El -Capitan", no longer include OpenSSL headers which will prevent the `openssl` -crate from compiling. +Although OpenSSL 0.9.8 is preinstalled on OSX this library is being phased out +of OSX and this crate also does not support this version of OpenSSL. To use this +crate on OSX you'll need to install OpenSSL via some alternate means, typically +homebrew: -For OSX 10.11 you can use brew to install OpenSSL and then set the environment variables -as described below. ```bash brew install openssl -export OPENSSL_INCLUDE_DIR=`brew --prefix openssl`/include -export OPENSSL_LIB_DIR=`brew --prefix openssl`/lib ``` -May be necessary clean the repository with `cargo clean` before build again. - -### Windows +### Windows MSVC -On Windows, consider building with [mingw-w64](http://mingw-w64.org/). -Build script will try to find mingw in `PATH` environment variable to provide -Cargo with location where openssl libs from mingw-w64 package may be found. +On MSVC it's unfortunately not always a trivial process acquiring OpenSSL. +Perhaps the easiest way to do this right now is to download [precompiled +binaries] and install them on your system. Currently it's recommended to +install the 1.1.0b light installation if you're choosing this route. -mingw-w64 can be easily installed by using [MSYS2](http://msys2.github.io/). Install MSYS2 according to the instructions, and then, from an MSYS2 Shell, install mingw-w64: +[precompiled binaries]: http://slproweb.com/products/Win32OpenSSL.html -32-bit: -```bash -pacman -S mingw-w64-i686-gcc -``` +Once a precompiled binary is installed you can configure this crate to find the +installation via an environment variable: -64-bit -```bash -pacman -S mingw-w64-x86_64-gcc +``` +set OPENSSL_DIR=C:\OpenSSL-Win64 ``` -and then install the mingw-w64 toolchain. +After that, you're just a `cargo build` away! -32-bit: -```bash -pacman -S mingw-w64-i686-toolchain -``` +### Windows GNU (MinGW) -64-bit: -```bash -pacman -S mingw-w64-x86_64-toolchain -``` +The easiest way to acquire OpenSSL when working with MinGW is to ensure you're +using [MSYS2](http://msys2.github.io) and to then execute: -Alternatively, install OpenSSL from [here][1]. Cargo will not be able to find OpenSSL if it's -installed to the default location. You can either copy the `include/openssl` -directory, `libssl32.dll`, and `libeay32.dll` to locations that Cargo can find -or pass the location to Cargo via environment variables: +``` +# 32-bit +pacman -S mingw-w64-i686-openssl -```bash -env OPENSSL_LIB_DIR=C:/OpenSSL-Win64 OPENSSL_INCLUDE_DIR=C:/OpenSSL-Win64/include cargo build +# 64-bit +pacman -S mingw-w64-x86_64-openssl ``` +And after that, a `cargo build` should be all you need! + ### Manual configuration rust-openssl's build script will by default attempt to locate OpenSSL via -pkg-config. This will not work in some situations, for example, on systems that -don't have pkg-config, when cross compiling, or when using a copy of OpenSSL +pkg-config or other system-specific mechanisms. This will not work in some +situations however, for example cross compiling or when using a copy of OpenSSL other than the normal system install. The build script can be configured via environment variables: -* `OPENSSL_LIB_DIR` - If specified, a directory that will be used to find - OpenSSL runtime libraries. -* `OPENSSL_INCLUDE_DIR` - If specified, a directory that will be used to find - OpenSSL headers. -* `OPENSSL_STATIC` - If specified, OpenSSL libraries will be statically rather - than dynamically linked. -If either `OPENSSL_LIB_DIR` or `OPENSSL_INCLUDE_DIR` are specified, then the -build script will skip the pkg-config step. +* `OPENSSL_DIR` - If specified, a directory that will be used to find + OpenSSL installation. It's expected that under this directory the `include` + folder has header files and a `lib` folder has the runtime libraries. +* `OPENSSL_STATIC` - If specified, OpenSSL libraries will be statically rather + than dynamically linked. -[1]: http://slproweb.com/products/Win32OpenSSL.html +If `OPENSSL_DIR` is specified, then the build script will skip the pkg-config +step. |