1.2. Installation¶
1.2.1. Virtual Environment¶
Before we will install groundwork, it would be great if we had a fresh and untouched Python installation. Luckily it is not necessary to do a complete new installation, because Python supports virtual environments.
These virtual environments are based on an already installed Python installation, but all additional installed packages not visible within the virtual environment.
Note
groundwork supports Python 2.7 and >=3.3 only. Please make sure your installed Python Environment is correct.
1.2.1.1. Creation¶
To create a new virtual environment, execute the following on the commandline:
python3 -m venv gw_venv
This will create the virtual environment gw_venv
(groundwork virtual environment) in the folder
gw_venv
of the current working directory.
1.2.1.2. Activation¶
To activate your new virtual environment, execute one of the following commands:
source gw_venv/bin/activate # For Linux
gw_venv\Scripts\activate.bat # For Windows
After that, the prefix (gw_venv)
should show up in front of your command prompt.
1.2.2. groundwork Installation¶
After activating your new virtual environment, we simply use pip
to install groundwork:
pip install groundwork
The virtual environment version of pip is used which installs groundwork to the virtual environment.
1.2.2.1. Alternative: Installation from source¶
If you want a installation from the latest groundwork source code, you need to clone the project repository and perform a development installation:
git clone https://github.com/useblocks/groundwork
cd groundwork
pip install -e .
pip install -e .
sets only links from the source code to the used virtual environment.
So changes on the code are directly available without any reinstallation (except if you have changed setup.py
).
Note
Before executing pip install -e .
please be sure that your working directory is the just cloned groundwork-folder!
The “.” in the command stands for “current working directory”.
Alternative you can give pip the complete path: pip install -e /my/folder/to/groundwork/
.
Not sure what the correct path is? It must contain a setup.py
file to be usable for installation.
1.2.2.2. Packages for test execution and documentation building¶
For a normal user the just installed packages are enough to run groundwork and all related applications.
However, developers normally want also to run tests and maybe generate the documentation by their own. For this tasks additional python packages are needed, which are not needed for normal usage. Therefore these package are not part of the normal installation and must be installed by the developers.
Luckily these dependencies are also collected in one single file, so that it can be used as input for pip
.
Let’s install these packages to be prepared:
pip install -r docs/doc-requirements.txt
pip install -r code/test-requirements.txt
1.2.3. Tests¶
Finally let’s check if groundwork was installed correctly, by trying to execute the command groundwork
:
>>> groundwork
Usage: groundwork [OPTIONS] COMMAND [ARGS]...
Options:
--help Show this message and exit.
Commands:
doc Shows the documentation
doc_list List all documents
doc_write Stores documents as files
plugin_list List all plugins
receiver_list List of all signal receivers
recipe_build Builds a given recipe
recipe_list Lists all recipes
signal_list List of all signals
If you see the above output, congratulation!
groundwork is installed and we can go on to examine the groundwork
command in the chapter Usage.