Installing a Lino developer environment¶
This document describes how to install a Lino developer environment on your computer. This is the easiest way to get started. You should read this document also if you plan to later evolve into a contributing developer as described in Setting up a Lino contributor environment.
This document is written for Debian and derived distributions. Other Linuxes should be pretty similar.
This document assumes you are familiar with the Linux shell at least for basic
file operations like
permissions, environment variables, bash scripts etc. Otherwise we suggest to
learn about Working in a UNIX shell.
Rather than installing Lino into your site-wide Python installation, you install it to a separate virtual Python environment, also known as a virtualenv
If virtualenvs are new to you: the reason for creating a new environment is to separate Lino from your system-wide Python. The main advantages are: if you are also developing other things with Python you might require different packages than what Lino uses, and there is the chance of version or dependency conflicts.
Also if you wish to remove Lino from your system you only need to remove the virtual environment rather than trying to remove Lino's dependencies from the system environment without breaking any other programs that use python.
Before using virtualenvs, we must install the feature:
$ sudo apt-get install python3-venv # Debian $ sudo dnf install python3-virtualenv # RedHat
In a developer environment we suggest
~/lino/env as your
default environment. So here we go:
$ mkdir ~/lino $ python3 -m venv ~/lino/env $ source ~/lino/env/bin/activate
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
Did you know?
You can deactivate a virtual environment with the command
deactivate. This switches you back to your machine's
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.
As a developer you probably don't want to type
~/lino/env/bin/activate each time you open a new terminal with
Ctrl+Alt+T. So you should set your default environment.
How to set up your default environment
Add the following line to your
(#) Instruct your favourite code editor to use this default environment when doing syntax checks or finding definitions.
$ pip install getlino
In case you have used getlino on your machine before (maybe another virtualenv, but the same machine), then you might want to delete your configuration files before going on:
$ rm ~/.getlino.conf $ sudo rm /etc/getlino/getlino.conf
$ getlino configure --no-devtools
It asks a lot of questions, but you can hit ENTER for each of them.
Warning : when getlino does not react to ENTER but asks a
[y or n]
question, then you should read it and understand it before you hit y.
getlino overwrites certain configuration files without making a backup copy.
Read twice before you hit y!
For details about each question or if something doesn't work as expected, see the documentation about getlino.
Remarks about some questions:
languages (The languages to set on new sites) [en]:This is just the default value that getlino will put for
settings.pyof new sites.
getlino startsite to create a first site:
$ getlino startsite noi first
You may replace the name
noi in above command by other names.
The available choices are listed in List of known Lino applications.
$ cd ~/lino/lino_local/first $ python manage.py runserver
Now start your browser, point it to http://127.0.0.1:8000/ and you should see something like this:
Congratulations! Enjoy the first Lino site running on your machine!
Using virtual environments can be a challenge for newbies. Here are some diagnostic tricks.
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://email@example.com/lino-framework/lino.git@91c28245c970210474e2cc29ab2223fa4cf49c4d#egg=lino -e git+git+ssh://firstname.lastname@example.org/lino-framework/book.git@e1ce69aaa712956cf462498aa768d2a0c93ba5ec#egg=lino_book -e git+git+ssh://email@example.com/lino-framework/noi.git@2e56f2d07a940a42e563cfb8db4fa7444d073e7b#egg=lino_noi -e firstname.lastname@example.org:lino-framework/xl.git@db3875a6f7d449490537d68b08daf471a7f0e573#egg=lino_xl lxml==3.6.4 ... Unipath==1.1 WeasyPrint==0.31 webencodings==0.5
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 the dependencies have been cached.
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.
A quick test when you want to see whether Lino is installed is to say "hello" to Lino:
$ python -m lino.hello Lino 21.9.0, Django 3.2.6, Python 3.6.8, Babel 2.9.0, Jinja 3.0.1, python-dateutil 2.8.0
- developer environment¶
A set of tools configured on the desktop computer of a Lino developer who wants to develop their own Lino application.
- contributor environment¶