Welcome | Get started | Dive | Contribute | Topics | Reference | Changes | More

Install your Lino developer environment

This document describes how to install a Lino developer environment on your computer.

developer environment

A set of tools installed on your computer so you can develop your own Lino application or otherwise contribute to Lino as a developer.

Set up a virtual Python environment

In order to keep Lino separate from your system-wide Python, you will first install a virtualenv and then install Lino into this environment.

virtualenv

A virtual Python environment. A directory tree containing a stand-alone Python installation where you can install and remove packages without modifying your computer system’s Python installation.

If you haven’t yet used virtualenvs, you must first install the feature:

$ sudo apt-get install python3-venv  # Debian
$ sudo dnf install python3-virtualenv  # RedHat

We suggest to install your developer environment under ~/lino, so here we go:

$ mkdir ~/lino
$ python3 -m venv ~/lino/env
$ . ~/lino/env/bin/activate

The dot (.) is a synonym for the source command. If you didn’t know it, read the manpage and What does ‘source’ do?

One last thing before we actually install Lino into that virtualenv: as a developer you probably don’t want to type . ~/lino/env/bin/activate each time you open a new terminal, so you should set it as your default environment.

default environment

The default virtualenv you use when developing.

Please add the following line to your ~/.bashrc file in order to define your default environment:

source ~/lino/env/bin/activate

Install and run getlino : the Lino installer

Now that your default environment is activated, let’s install getlino : the Lino installer:

$ pip install getlino

Now run getlino configure with the following options:

$ getlino configure --clone --devtools --appy

It asks a lot of questions, but you can hit ENTER for each of them. When it does not react to ENTER but asks a [y or n] question, then make sure to read the question and understand it before you hit y. For details about each question or if something doesn’t work as expected, see Troubleshooting below or the documentation about getlino : the Lino installer.

The process of cloning the repositories takes some time. Lino is a whole little collection of repositories and applications! See Repositories of the Lino framework if you are curious. You don’t need to dive into each of them right now, but you must at least install them so that your environment is complete.

When getlino has finished, add manually the following line to your .bashrc file:

source ~/.lino_bash_aliases

The ~/.lino_bash_aliases file installs several shell commands, we will have a deeper look at them in More about your developer environment.

Is Lino installed?

A quick test when you want to see whether Lino is installed is to say “hello” to Lino:

$ python -m lino.hello
Lino 24.9.3, Django 5.1.2, Python 3.10.12, Babel 2.16.0, Jinja 3.1.4, python-dateutil 2.9.0.post0

Python’s -m command-line switch instructs it to just import the specified module (here lino.hello) and then to return to the command line.

Run a demo project

A Lino developer environment comes with a lot of demo projects.

demo project

A directory with at least two files settings.py and manage.py, which define a Django project directory (a Lino site) that can be used for testing, demonstrating and explaining Lino.

Please try one of the demo projects:

$ go polly  # alias for: cd ~/lino/repositories/book/lino_book/projects/polly
$ pm prep --noinput  # alias for: python manage.py prep --noinput
$ runserver  # alias for: python manage.py runserver

Point your browser to http://localhost:8000 and you should see something like the following:

If you get this screen, then you can head over to the next page.

Otherwise you are going to learn a bit more :-) The following Troubleshooting section will maybe help you. And keep in mind that this is a reason to ask for support from your mentor because your problem will probably help us to make Lino and this Developer Guide a bit better.

Troubleshooting

polly is the nickname of a demo project. We will discover more demo projects in Discover some demo projects.

Before starting a development server on a demo project for the first time, you must initialize its database using the pm prep command.

The shell commands go, pm and runserver are defined by the ~/.lino_bash_aliases file.

Note the difference between inv prep and the pm prep command. inv prep runs the pm prep command for each demo project of a repository. The demo projects of a repository are declared in the tasks.py file. You can run the pm prep command for all demo projects by going to the root directory of the book project and saying inv prep:

$ go book   # alias for: cd ~/lino/env/repositories/book
$ inv prep

More about getlino

The getlino script does a lot of work. These commands take some time when you run them the first time on your machine because they will download and install all Python packages needed by Lino. If you install them a second time into another environment, the process will be quicker because pip caches the downloaded packages.

languages (The languages to set on new sites) [en]: This is just the default value that getlino will put for languages in the settings.py of new sites.

In some circumstances getlino will say “The following command was not executed because you cannot sudo”, followed by an “apt-get install” command. Consider running these commands manually.

In case you have used getlino on your machine before (maybe in another virtualenv, but on the same machine), then you might want to delete your configuration files before installing again:

$ rm ~/.getlino.conf
$ sudo rm /etc/getlino/getlino.conf

The --appy option tells getlino configure to install a LibreOffice server on your machine. Some of the demo examples use lino_xl.lib.appypod for producing printable pdf files. That’s why you need a LibreOffice server on your system. Details about what getlino does are described in More about the LibreOffice service.

More about virtualenvs

Using virtual environments can be a challenge. Here are some diagnostic tricks.

You can deactivate a virtual environment with the command deactivate. This switches you back to your machine’s system-wide environment.

You can switch to another virtualenv simply by activating it, you don’t need to deactivate the current one first.

You should never rename a virtualenv (they are not designed for that), but you can easily create a new one and remove the old one.

To learn more, read Dan Poirier’s post Managing multiple Python projects: Virtual environments where he explains what they are and why you want them.

After creating a new environment, you should always update pip and setuptools to the latest version:

$ pip install -U pip setuptools
Collecting pip
  Using cached https://files.pythonhosted.org/packages/43/84/23ed6a1796480a6f1a2d38f2802901d078266bda38388954d01d3f2e821d/pip-20.1.1-py2.py3-none-any.whl
Collecting setuptools
  Downloading https://files.pythonhosted.org/packages/8e/11/9e10f1cad4518cb307b484c255cae61e97f05b82f6d536932b1714e01b47/setuptools-49.2.0-py3-none-any.whl (789kB)
    100% |████████████████████████████████| 798kB 1.1MB/s
Installing collected packages: pip, setuptools
  ...
Successfully installed pip-20.1.1 setuptools-49.2.0

How to see which is your current virtualenv:

$ echo $VIRTUAL_ENV
/home/joe/lino/env

$ which python
/home/joe/lino/env/bin/python

How to see what’s installed in your current virtualenv:

$ pip freeze

The output will be about 60 lines of text, here is an excerpt:

alabaster==0.7.9
appy==0.9.4
argh==0.26.2
...
Django==1.11.2
...
future==0.15.2
...
-e git+git+ssh://git@github.com/lino-framework/lino.git@91c28245c970210474e2cc29ab2223fa4cf49c4d#egg=lino
-e git+git+ssh://git@github.com/lino-framework/book.git@e1ce69aaa712956cf462498aa768d2a0c93ba5ec#egg=lino_book
-e git+git+ssh://git@github.com/lino-framework/noi.git@2e56f2d07a940a42e563cfb8db4fa7444d073e7b#egg=lino_noi
-e git+git@github.com:lino-framework/xl.git@db3875a6f7d449490537d68b08daf471a7f0e573#egg=lino_xl
lxml==3.6.4
...
Unipath==1.1
WeasyPrint==0.31
webencodings==0.5

The -e command-line switch for pip causes it to use the “development” mode. The first argument after -e is not a project name but a path to a directory of your local filesystem. Development mode means that these modules run “directly from source”. pip does not copy the sources to your Python site_packages, but instead adds a link to them.