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.
In addition to a Python installation, there are a few system dependencies needed when contributing:
Installing from a git clone
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,hdbscan,cupy]
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”
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
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.7, you create a new environment with Python 3.7:
> conda create -n libertem-3.7 python=3.7
Now you can create
python3.7.bat in your normal LiberTEM environment
python3.9.bat and make it execute the Python interpreter of
your new libertem-3.7 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.7\python.exe %*