Setting up a development environment

When you want to develop LiberTEM itself, or run the latest git version, the installation works a bit differently as opposed to installing from PyPI. As a first step, please follow the instructions for creating a Python virtual environment from the Installation section. Then, instead of installing from PyPI, follow the instructions below.

Prerequisites

In addition to a Python installation, there are a few system dependencies needed when contributing:

pandoc and graphviz are needed to build and test the documentation.
Node.js is needed for rebuilding the LiberTEM GUI. On Linux, we recommend to install via package manager, on Windows the installer should be fine. Choose the current LTS version.

Installing from a git clone

Note

Distinguish between installing a released version and installing the latest development version. Both installing from PyPI and Installing from a git clone use pip, but they do fundamentally different things. python -m pip install libertem downloads the latest release from PyPI.

Changing directory to a git clone and running python -m pip install -e . installs from the local directory in editable mode. “Editable mode” means that the source directory is “linked” into the current Python environment rather than copied. That means changes in the source directory are immediately active in the Python environment.

Installing from a git clone in editable mode is the correct setup for development work and using the latest features in the development branch. Installing from PyPI is easier and preferred for production use and for new users.

If you want to follow the latest development, you should install LiberTEM from a git clone. As a prerequisite, you need to have git installed on your system. On Linux, we suggest using the git package that comes with your package manager. On Windows, you can use one of the many available clients, like git for windows, GitHub Desktop, TortoiseGit, or the git integration of your development environment.

$ git clone https://github.com/LiberTEM/LiberTEM

Or, if you wish to contribute to LiberTEM, create a fork of the LiberTEM repository by following these steps:

Log into your GitHub account.
Go to the LiberTEM GitHub home page.
Click on the fork button:
Clone your fork of LiberTEM from GitHub to your computer

$ git clone https://github.com/your-user-name/LiberTEM

More information about forking a repository. For a beginner-friendly introduction to git and GitHub, consider going through the following resources:

This free course covers the essentials of using Git.
Practice pull request in a safe sandbox environment.
Sample workflow for contributing code.

Activate the Python environment (conda or virtualenv) and change to the newly created directory with the clone of the LiberTEM repository. Now you can start the LiberTEM installation. Please note the dot at the end, which indicates the current directory!

(libertem) $ python -m pip install -e .

This should download the dependencies and install LiberTEM in the environment. Please continue by reading the GUI usage.

Installing extra dependencies works just like when installing LiberTEM from PyPI:

(libertem) $ python -m pip install -e .[torch,cupy]

Updating

If you have installed from a git clone, you can easily update it to the current status. Open a command line in the base directory of the LiberTEM clone and update the source code with this command:

$ git pull

The installation with python -m pip install -e has installed LiberTEM in “editable” mode. That means the changes pulled from git are active immediately. Only if the requirements for installed third-party packages have changed, you should re-run python -m pip install -e . in order to install any missing packages.

Setting up tox on Windows

Note

This doesn’t seem to work on the newest tox major release 4.x anymore. We are still figuring out how to make it work. Help is appreciated!

We are using tox to run our tests. On Windows with Anaconda, you have to create named aliases for the Python interpreter before you can run tox so that tox finds the python interpreter where it is expected. Assuming that you run LiberTEM with Python 3.9, place the following file as python3.9.bat in your LiberTEM conda environment base folder, typically %LOCALAPPDATA%\conda\conda\envs\libertem\, where the python.exe of that environment is located.

@echo off
REM @echo off is vital so that the file doesn't clutter the output
REM execute python.exe with the same command line
@python.exe %*

To execute tests with Python 3.12, you create a new environment with Python 3.12:

> conda create -n libertem-3.12 python=3.12

Now you can create python3.12.bat in your normal LiberTEM environment alongside python3.9.bat and make it execute the Python interpreter of your new libertem-3.12 environment:

@echo off
REM @echo off is vital so that the file doesn't clutter the output
REM execute python.exe in a different environment
REM with the same command line
@%LOCALAPPDATA%\conda\conda\envs\libertem-3.12\python.exe %*