Lino Developer's Guide

This is the central meeting place for Lino developers. The Getting started section is useful for system administrators as well.

Getting started

This document describes how to install Lino. System requirements. Set up a Python environment. Running your first Lino site.

It assumes you are familiar with the Linux shell at least for basic file operations like ls, cp, mkdir, rmdir, file permissions, environment variables, bash scripts etc. Otherwise we suggest to learn about Working in a UNIX shell.

System requirements

Lino theoretically works under Python 3, but we currently still recommend Python 2. If you just want it to work, then choose Python 2. Otherwise consider giving it a try under Python 3 and report your experiences.

We assume you have pip installed. pip is not automatically bundled with Python 2, but it has become the de facto standard. Here is how to install it on Debian:

$ sudo apt-get install python-pip

You will need to install git on your computer to get the source files:

$ sudo apt-get install git

Lino requires lxml, which has some extra requirements before you can install it with pip:

$ sudo apt-get build-dep lxml

Note: if you get an error message You must put some 'source' URIs in your sources.list, then (in Ubuntu) open System Settings ‣ Software & Updates and make sure that Source code is checked.

Similar requirement for applications which use lino.modlib.weasyprint:

$ sudo apt-get install libffi-dev

Set up a Python environment

Before you actually install Lino into your Python, we recommend to create a new Python environment using virtualenv. On a Debian system this means something like:

$ sudo pip install virtualenv
$ mkdir ~/virtualenvs
$ virtualenv ~/virtualenvs/a

To activate this environment, you will type:

$ . ~/virtualenvs/a/bin/activate

In a normal situation, all your Python projects can use the same virtual environment. So you probably want to add above line to your .bashrc file:

$ echo ". ~/virtualenvs/a/bin/activate" >> ~/.bashrc

Notes

We chose a as name for this environment. You might prefer lino, dev or my_first_environment.

If virtualenvs are new to you, then read Dan Poirier’s post Managing multiple Python projects: Virtual environments where he explains what they are and why you want them.

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

You can deactivate a virtual environment with the command deactivate. This switches you back to your machine’s global environment. You can switch to another virtualenv simply by activating it. You don’t need to deactivate the current one before. 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.

Get the sources

You might theoretically install Lino using pip install lino, but this method isn’t currently being tested very thoroughly. So in most cases we currently recommend to use the development version because you will probably want to use Lino’s newest features before they get released on PyPI.

Create a directory (e.g. ~/repositories) meant to hold your working copies of version-controlled software projects, cd to that directory and do:

$ mkdir ~/repositories
$ cd ~/repositories
$ git clone https://gitlab.com/lino-framework/lino.git
$ git clone https://gitlab.com/lino-framework/xl.git
$ git clone https://gitlab.com/lino-framework/cosi.git
$ git clone https://gitlab.com/lino-framework/book.git

(Alternatively, to use the old, now-historical read-only repository, you could do:

$ mkdir ~/repositories
$ cd ~/repositories
$ git clone https://github.com/lino-framework/lino.git
$ git clone https://github.com/lino-framework/xl.git
$ git clone https://github.com/lino-framework/cosi.git
$ git clone https://github.com/lino-framework/book.git

)

You should now have four directories called ~/repositories/lino, ~/repositories/xl , ~/repositories/cosi and ~/repositories/book, each of which contains a file setup.py and a whole tree of other files and directories.

One possible problem here is that the Lino repository has a big size. If you just want to try out the latest version and will never submit any pull request, then you can reduce this from 300MB to 63MB by adding --depth 1 option (as explained in this question on stackoverflow or Nicola Paolucci’s blog entry How to handle big repositories with git).

Installation

Now you are ready to “install” Lino, i.e. to tell your Python interpreter where the source file are, so that you can import them from within any Python program.

Commands:

$ pip install -e lino
$ pip install -e xl
$ pip install -e cosi
$ pip install -e book

These commands take some time because they will download and install all Python packages needed by Lino.

Note that the -e command-line switch for pip causes it to use the “development” mode. 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. The first argument after -e is not a project name but a directory.

Telling your Lino version

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

$ python -m lino.hello
Lino 1.7.6, Django 1.9.11, Python 2.7.12, Babel 2.3.4, Jinja 2.8, Sphinx 1.5a3, python-dateutil 2.6.0, OdfPy ODFPY/1.3.3, docutils 0.12, suds 0.4, PyYaml 3.12, Appy 0.9.4 (2016/07/28 13:39)

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.

Actually the Lino version number is not enough when using a developer installation of Lino. The Lino codebase repository changes almost every day, while the version is incremented only when we do an official release to PyPI.

So as a developer you will simply upgrade your copy of the code repositories often. Here is a quick series of commands for getting the latest version:

$ cd ~/repositories/lino ; git pull
$ cd ~/repositories/xl ; git pull
$ cd ~/repositories/cosi ; git pull
$ cd ~/repositories/book ; git pull
$ find ~/repositories -name '*.pyc' -delete

This process is fully described in How to update your copy of the repositories.

Troubleshooting

Using virtual environments seems to be one of the biggest challenges for newbies. Here are some diagnostic tricks.

How to see which is your current virtualenv:

$ echo $VIRTUAL_ENV
/home/luc/virtualenvs/a

$ which python
/home/luc/virtualenvs/a/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.9.10 ... 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/cosi.git@2e56f2d07a940a42e563cfb8db4fa7444d073e7b#egg=lino_cosi -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 Initialize the demo databases The Lino Book contains a series of demo projects, each of which has its own database. These databases need to be initialized before you can use these projects.

The easiest way to do this is to run the inv initdb command from within your copy of The Lino Book repository:

$ cd ~/repositories/book
$ inv initdb

The inv command has been installed on your system (more precisely: into your Python environment) by the invoke package, which itself has been required by atelier, which is another Python package developed by Luc.

The inv command is a kind of make tool which works by looking for a file named tasks.py. The Lino repository contains such a file, and this file uses lino.invlib, which (together with atelier.invlib from which it inherits) defines a whole series of commands like inv initdb or inv test.

Running your first Lino site

You can now cd to any subdir of lino_book.projects and run a development server:

$ cd lino_book/projects/min1
$ python manage.py runserver

Now start your browser, point it to 127.0.0.1:8000/ and play around.

Don’t stay in min1, also try the other projects below lino_book.projects. None of them is a “killer app”, they are just little projects used for testing and playing.

Where to go from here

As your next step, we now suggest to Create a local Lino project.

1. Create a local Lino project : The first Lino application running on your machine. It’s easier than with Django. A settings.py and a manage.py.
2. Initializing the demo databases : More about the initdb and initdb_demo commands.

Your first application

1. Writing your own Python fixtures : Playing with Python fixtures. Writing your own Python fixtures.
2. The Lino Polls tutorial : In this section we are going to convert the “Polls” application from Django’s tutorial into a Lino application. This will illustrate some differences between Lino and Django.
3. An introduction to Tables : Models, tables and views. What is a table? Designing your tables. Using tables without a web server.
4. Introduction to layouts : About layouts, detail windows, data elements and panels.