From fd76acfe574468f52acb3ff5bf5512b761d3c4eb Mon Sep 17 00:00:00 2001 From: Anatolii Lishchynskyi Date: Thu, 30 Nov 2023 23:41:26 +0200 Subject: [PATCH] Update PyThemis installation instructions (#317) * Update PyThemis installation instructions Mention that old pythemis_install is deprecated, don't remove that part yet. Describe how to build a .whl package and install it into venv. Draft for system package building and installing. * Update PyThemis build/install docs * Rename pythemis_install -> pythemis_old_install * PyThemis Debian packaging manual Also, mention needed packages for building wheel * Update .deb building steps * Rename pythemis_old_install -> pythemis_install * Update PyThemis installation docs * Comment RHEL-related PyThemis installation * Uncomment rpm building, other changes * Update PyThemis installation docs * Update content/themis/languages/python/installation.md Co-authored-by: vixentael * Update after review --------- Co-authored-by: vixentael --- .../themis/languages/python/installation.md | 146 +++++++++++++++++- content/themis/languages/wasm/installation.md | 3 + 2 files changed, 147 insertions(+), 2 deletions(-) diff --git a/content/themis/languages/python/installation.md b/content/themis/languages/python/installation.md index 68ae4ac5..345e0162 100644 --- a/content/themis/languages/python/installation.md +++ b/content/themis/languages/python/installation.md @@ -73,7 +73,144 @@ Once PyThemis is installed, you can [try out code examples](../examples/). ## Building latest version from source If the stable package version does not suit your needs, -you can manually build and install the latest version of Themis from source code. +you can manually build python wheel or `.deb`/`.rpm` package and install the latest version of Themis from source code. + +### Python wheel + +A package suitable for installation in Python virtual environments + + 1. [Build and install Themis Core library](/themis/installation/installation-from-sources/) + into your system. + + 2. Install Python dependencies + + You'll need `setuptools` and `wheel` + + * Install globally + + For Debian, Ubuntu: + + ```bash + sudo apt install python3-setuptools python3-wheel + ``` + + For CentOS, RHEL: + + ```bash + sudo yum install python3-setuptools python3-wheel + ``` + + * Or install into virtualenv + + ```bash + # create and activate virtualenv if not done yet + pip install setuptools wheel + ``` + + 3. Create a PyThemis package + + {{< hint info >}} + If you installed dependencies globally, virtualenv should not be activated during wheel + generation since needed packages won't be visible in an isolated environment. + {{< /hint >}} + + ```bash + make pythemis_make_wheel + ``` + + Result package filename will be printed at the end, like this: + ``` + Result: src/wrappers/themis/python/dist/pythemis-0.14.0-py2.py3-none-any.whl + ``` + + 4. Install PyThemis + + ```bash + # activate virtualenv if not done yet + make pythemis_install_wheel + ``` + + Or manually run `pip install path/to/pythemis-...-none-any.whl` (the package file previously created). + If the virtual environment already contained PyThemis of the same version, + add `--force-reinstall` option to rewrite the previous package. + +### OS package + +A package for system-wide installation, for Debian-like and RHEL-like distros + + 1. [Build and install Themis Core library](/themis/installation/installation-from-sources/) + into your system. + + 2. Install Python dependencies + + For Debian, Ubuntu: + + ```bash + sudo apt install lsb-release python3-pip ruby + sudo gem install fpm + ``` + + For CentOS, RHEL: + + ```bash + sudo yum install redhat-lsb-core python3-pip ruby rpm-build + sudo gem install fpm + ``` + + On RHEL you also need to have working `pip` command. If it's not, and you only got `pip3`, + create a symlink like this: `sudo ln -s $(which pip3) /usr/bin/pip`. + + 3. Create a PyThemis package + + For Debian, Ubuntu: + + ```bash + make deb_python + ``` + + For CentOS, RHEL: + + ```bash + make rpm_python + ``` + + The result will be located at `build/deb/python3-pythemis_...all.deb` + or `build/rpm/python3-pythemis_...all.rpm` respectively. + + 4. Install PyThemis + + For Debian, Ubuntu: + + ```bash + sudo make pythemis_install_deb + ``` + + For manual installation, there are two ways: + 1. `sudo apt install ./path/to/package.deb` (the `./` is important here) + 2. `sudo dpkg -i path/to/package.deb` (need to install `python3-six` and `libthemis` beforehands) + + For CentOS, RHEL: + + ```bash + sudo make pythemis_install_rpm + ``` + + Or manually run `sudo yum install ./path/to/package.rpm` + +## Building Themis < 0.15 version from sources (deprecated) + +{{< hint warning >}} +The instructions below are relevant only for Themis older than 0.15. Most likely, you don't need to follow them, and should install the latest Themis instead. +{{< /hint >}} + +{{< hint warning >}} +[PEP 668](https://peps.python.org/pep-0668/) changed the way Python packages are managed. +It is now recommended to use `pip install` to only install packages into isolated virtual environments +while installing things system-wide should be done using OS package manager (like `apt` or `rpm`). +This means running `sudo make pythemis_install` is no longer recommended as it copies files +into system-managed Python directory (like `/usr/lib/python3.X/site-packages`) that is no longer maintained by `pip`. +Consider building a `.whl` and installing it into your venv instead. +{{< /hint >}} 1. [Build and install Themis Core library](/themis/installation/installation-from-sources/) into your system. @@ -81,7 +218,7 @@ you can manually build and install the latest version of Themis from source code 2. Install PyThemis package from the source code: ```bash - make pythemis_install + sudo make pythemis_install ``` The package will be installed globally into the system. @@ -91,3 +228,8 @@ you can manually build and install the latest version of Themis from source code ```bash make prepare_tests_all test_python ``` + +To remove PyThemis after using `pythemis_install`, run +```bash +sudo pip uninstall --break-system-packages pythemis +``` diff --git a/content/themis/languages/wasm/installation.md b/content/themis/languages/wasm/installation.md index 5c2e5bc6..4799d579 100644 --- a/content/themis/languages/wasm/installation.md +++ b/content/themis/languages/wasm/installation.md @@ -168,6 +168,9 @@ to learn more about managing toolchain versions. emmake make wasmthemis ``` + Be aware that build may fail if non-WASM Themis was previously build in this same directory. + In that case, run `make clean` before building WasmThemis. + The resulting package will be placed into `build/wasm-themis.tgz` in Themis source tree.