Welcome | Get started | Dive into Lino | Contribute | Reference
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.
Set up a virtual Python environment¶
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. There are at least two reasons for this:
other software on your computer might require different Python packages than those required by Lino, and there is the chance of version or dependency conflicts.
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
$ . ~/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?
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
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.
Set your default virtualenv¶
As a developer you probably don't want to type source
~/lino/env/bin/activate
each time you open a new terminal with
Ctrl+Alt+T. So you should set your default environment.
- default environment¶
The default virtualenv you use when developing.
How to set up your default environment
Add the following line to your
~/.bashrc
file:source ~/lino/env/bin/activate
(#) Instruct your favourite code editor to use this default environment when doing syntax checks or finding definitions.
Run getlino¶
Make sure your default environment is activated and then install getlino via pip:
$ pip install getlino
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 going on:
$ rm ~/.getlino.conf
$ sudo rm /etc/getlino/getlino.conf
Now run getlino configure
with the following options:
$ getlino configure --clone --devtools
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
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 Troubleshooting below or the documentation about getlino.
When getlino has finished, add manually the following line to your
.bashrc
file:
source ~/.lino_bash_aliases
Play with the demo projects¶
Getlino also installs the Lino Book project. The Lino book is a special project. It is not an application, and it is not released on PyPI. It makes sense only for developers. It contains the main test suite for Lino. It contains a lot of demo projects.
You can now cd
to any subdir of lino_book.projects
and run a
development server. Before starting a development server on a demo project for
the first time, you must initialize its database using the pm prep
command.
Try one of the demo projects:
$ go noi1r
$ pm prep
$ pm runserver
Point your browser to http://localhost:8000
We will have a deeper look at some demo projects in Discover Lino.
Troubleshooting¶
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://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
Behind the scenes¶
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
:
$ cd ~/lino/env/repositories/book
$ inv prep
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.
Remarks about some questions:
languages (The languages to set on new sites) [en]:
This is just the default value that getlino will put forlanguages
in thesettings.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.
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.
A quick test when you want to see whether Lino is installed is to say "hello" to Lino:
$ python -m lino.hello
Lino 23.9.1, Django 4.2.2, Python 3.10.12, Babel 2.12.1, Jinja 3.1.2, python-dateutil 2.8.2
In case you didn't know: 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.