Development¶

This section is about the requirements necessary to develop arrangeit software.

System requirements¶

GNU/Linux¶

Ubuntu¶

To start arrangeit development on Ubuntu, you should install some system packages by issuing the following command:

$ sudo apt-get install python3-dev git gcc pkg-config libcairo2-dev \
    libgirepository1.0-dev gir1.2-gtk-3.0  gir1.2-wnck-3.0

If you are planning to build latexpdf documentation then you should install some additional packages with:

$ sudo apt-get install texlive texlive-latex-extra latexmk

elementaryOS 5.0 (juno)¶

$ sudo apt-get install python3-dev python3-venv git python3-tk \
    pkg-config libgirepository1.0-dev

Debian Stretch¶

$ su
# apt-get install python3-dev python3-venv python3-tk git pkg-config \
    libcairo2-dev libgirepository1.0-dev gir1.2-gtk-3.0 gir1.2-wnck-3.0

Debian Buster¶

$ su
# apt-get install python3-dev python3-venv python3-tk git gcc \
    pkg-config libcairo2-dev libgirepository1.0-dev

Manjaro 18.04 Xfce¶

$ sudo pacman -S gobject-introspection tk

MS Windows¶

Official Python 3 installer and git for Windows probably represent the easiest way to start development on MS Windows.

Mac OS X¶

Download the official installer and install Python 3 by executing .pkg file. Finally, run provided post-install script Install Certificates.command.

Python requirements¶

You should develop arrangeit in a dedicated virtual environment. If you don’t have any other preferred way, then probably the easiest way to create a virtual environment would be venv integrated with Python 3.5+.

For example, if you place your projects in projects directory and path to arrangeit root directory is /home/yourusername/projects/arrangeit (or c:\Users\yourusername\projects\arrangeit on MS Windows), then you may create a directory inside projects directory to hold your virtual environments.

$ cd ~/projects
$ mkdir venvs
$ cd venvs

Create a new virtual environment with:

$ python3 -m venv arrangeit

The virtual environment is activated on GNU/Linux from venvs directory with:

$ source arrangeit/bin/activate

Or in MS Windows with:

Install the base requirements by issuing the following from the project’s root directory:

(arrangeit) $ python -m pip install -U -r requirements/linux.txt

And all the necessary Python dependency packages for arrangeit development with:

(arrangeit) $ python -m pip install -U -r requirements/base_development.txt

Additional tools¶

pygettext¶

pygettext is a Python wrapper for xgettext and it ships with Python. To prepare translation template, run the following command on Ubuntu from the project’s root directory:

find ./arrangeit -iname "*.py" | xargs pygettext3 --verbose --extract-all \
  --default-domain=arrangeit --output-dir=./arrangeit/locale

Create a language directory inside locale directory, and inside that language directory create another directory with the name LC_MESSAGES. Finally, copy arrangeit translation template into that directory and rename it to arrangeit.po.

Here’s how it was done from the project’s root directory for the Croatian language:

$ mkdir -p arrangeit/locale/hr_HR/LC_MESSAGES
$ cp arrangeit/locale/arrangeit.pot arrangeit/locale/hr_HR/LC_MESSAGES/arrangeit.po

If an existing translation needs to be updated after arrangeit.pot has been changed, then you should update the differences with msgmerge:

$ msgmerge --update arrangeit/locale/hr_HR/LC_MESSAGES/arrangeit.po arrangeit/locale/arrangeit.pot

After the translation is finished, compile the language file with msgfmt:

$ cd arrangeit/locale/hr_HR/LC_MESSAGES
$ msgfmt -o arrangeit.mo arrangeit.po

If you use Poedit for translation, then instead of the last command you may create compiled file by clicking the Save button in Poedit.

black¶

Any code should be formatted by black before commit.

It should have been installed together with other development requirements (python -m pip install -r requirements/base_development.txt) or you may install it separately with:

$ python3 -m pip install black

Run it from the root directory by:

$ black arrangeit

pyflakes¶

Install pyflakes linter with:

$ python3 -m pip install pyflakes

Run it from the project’s root directory by:

$ python3 -m pyflakes arrangeit

py2deb¶

py2deb is used to build GNU/Linux installation package.

Run the following command to install py2deb dependencies on Debian/Ubuntu:

$ sudo apt-get install dpkg-dev fakeroot lintian python3-pip

py2deb’s dependency pip-accel needs pip version to be 7.x, so the following commands should probably be run inside a Python 3 virtual environment created for the purpose (add --user argument to pip3 if you want to install py2deb system-wide):

$ pip3 install py2deb $ pip3 install pip-accel # it will downgrade pip to version <8.0

And then run the following command inside the project’s root directory to create Debian installation package in ./dist/ directory:

$ mkdir dist
$ py2deb -r ./dist/ --no-name-prefix=arrangeit -y \
    --use-system-package=Pillow,python3-pil \
    --use-system-package=python-xlib,python3-xlib \
    --use-system-package=six,python3-six \
    .

PyInstaller¶

PyInstaller is used to build MS Windows installation package.

starter.py script is created in the project’s root directory for the purpose of PyInstaller’s dependencies collecting. The specification file pyinstaller.spec in the same directory is used to produce MS Windows executable by the following call:

(arrangeit) $ python -OO -m PyInstaller pyinstaller.spec

SonarQube¶

SonarQube is an open-source platform for inspection of code quality for detecting bugs, code smells, and security vulnerabilities.

Starting server¶

$ ~/opt/repos/sonarqube-7.7/bin/linux-x86-64/sonar.sh console

Starting scanner¶

You should add scanner executable to your PATH. For example, by adding the following line to your ~/.bashrc:

export PATH=$PATH:~/opt/repos/sonar-scanner/bin

To start scanning, run the scanner from the root directory of the project with:

$ sonar-scanner

For additional information read the scanner documentation.

Administration¶

Prepare coverage’s XML report by running the following in the project’s root directory:

(arrangeit) $ python -m pytest -v --cov-report xml:tests/unit/coverage-linux.xml --cov=arrangeit

Overview¶

Open your browser and point it to http://localhost:9000. Login as admin/admin.