Welcome | Get started | Dive | Contribute | Topics | Reference | Changes | More
More about your developer environment¶
Introducing atelier¶
As a Lino developer you are going to use atelier
, a minimalist
developer project management tool. A “project”, for atelier, is any directory
containing at least a file tasks.py
.
You “activate” a project by opening a terminal and changing to its directory. That’s all. Almost all. Read on.
An atelier project usually corresponds to a public code repository (using Git or Mercurial). But you can have unpublished projects that have no repo at all.
One atelier project can contain one or more demo projects.
An atelier project usually corresponds to a given Python package to be published on PyPI.
An atelier project can have a number of Sphinx document trees (default is one tree named
docs
).
Your atelier projects don’t need to be under a single base directory. You
will have different project base directories. One of them is
~/lino/lino_local
, but another one is ~/lino/env/repositories
:
- ~/lino/env/repositories¶
The base directory for every repository you cloned from GitLab.
Configuring atelier¶
To finish the installation of your Lino developer environment, you must create
your ~/.atelier/config.py
file. You must create this file yourself,
manually:
$ mkdir ~/.atelier
$ nano ~/.atelier/config.py
Add the following content:
from pathlib import Path
for root in ["~/lino/lino_local", "~/lino/env/repositories"]:
for p in Path(root).expanduser().iterdir():
if p.is_dir():
add_project(str(p))
The atelier config file tells atelier
the list of your projects. Letting
atelier
know where your projects are has the advantage that you can run
the per_project
script (or its alias pp
) to run a given command
over many projects.
Usage examples¶
You can now play around in your environment.
See a list of your atelier projects:
$ pp -l
========= ========= ==========================================
Project Status URL
--------- --------- ------------------------------------------
lino master! http://www.lino-framework.org
xl master http://www.lino-framework.org
noi master http://noi.lino-framework.org
cosi master http://cosi.lino-framework.org
avanti master http://avanti.lino-framework.org/
vilma master http://vilma.lino-framework.org
care master http://care.lino-framework.org
tera master http://tera.lino-framework.org
book master! http://www.lino-framework.org
voga master http://voga.lino-framework.org
welfare master https://welfare.lino-framework.org
amici master http://amici.lino-framework.org
========= ========= ==========================================
Change to ~/lino/env/repositories/lino
and download the latest version
of Lino:
$ go lino
$ git pull
Do the same for all your cloned repositories:
$ pp git pull
Run the full test suite in Developer Guide:
$ go book
$ inv prep test
(inv prep test
is equivalent to inv prep
followed by inv
test
.)
Build a local copy of the Lino Developer Guide:
$ go book
$ inv bd
Afterwards you can start your browser on the generated output:
$ python -m webbrowser docs/.build/index.html
Building the docs might not work out of the box, it is a topic of its own. See Building the Lino docs.
It happens that I type the following before leaving my computer for getting a cup of coffee:
$ pp inv prep test bd
Which is: in each Lino repository, run inv prep
followed by inv
test
followed by inv bd
.
Bash aliases installed by getlino¶
Remember that a file ~.lino_bash_aliases
was created in
Install your Lino developer environment and we asked you to source it from within your
~/.bash_aliases
or ~/.bashrc
file.
- ~/.lino_bash_aliases¶
Contains several aliases and shell functions.
When installing Lino on a production server it is a system-wide file in
/etc/getlino/lino_bash_aliases
.
The following command aliases are installed by ~/.lino_bash_aliases
:
- go¶
cd
to one of your local project directories using its nickname.In case you also use the Go programming language on your computer, you should obviously edit your pick another name than “go”.
The go
command is a shell function in your ~/.lino_bash_aliases
and looks like this:
function go() {
for BASE in ~/lino/lino_local ~/lino/env/repositories ~/lino/env/repositories/book/lino_book/projects
do
if [ -d $BASE/$1 ] ; then
cd $BASE/$1;
return;
fi
done
echo Oops: no project $1
return -1
}
So there are three “types” of nicknames:
$ go lino # cd ~/lino/env/repositories/lino
$ go first # cd ~/lino/lino_local/first
$ go min1 # cd ~/lino/env/repositories/book/lino_book/projects/min1
Note how the for BASE in
of the go
command also loops over the
directory ~/lino/env/repositories/book/lino_book/projects
. This
directory contains our demo projects.
- runserver¶
An alias for
LINO_LOGLEVEL=DEBUG python manage.py runserver
- pm¶
An alias for
python manage.py
, in other words for executing adjango-admin
command.This alias is installed by
getlino configure
.
- a¶
Expands to
. env/bin/activate
.This alias is installed by
getlino configure
.
- pywhich¶
Shortcut to quickly show where the source code of a Python module is coming from.
This is useful e.g. when you are having troubles with your virtual environments.
The pywhich
command is actually also a simply shell function:
function pywhich() {
python -c "import $1; print($1.__file__)"
}
How to change the location of your repositories¶
The following it not much tested. Read and follow at your own risk or together with your mentor.
Imagine that for some reason you want to trash your virtualenv and
create it anew. The longest waiting time when you installed your developer
environment was to download all the repositories from GitLab. You can avoid
downloading them again by moving your repositories to another location and to
inform getlino about it by saying getlino configure --repos-base
:
$ mv ~/lino/env/repositories ~/
$ getlino configure --repos-base ~/repositories
The getlino
command has a quite primitive user interface. But it is less
stupid that the first impression might leave. For example it knows that it has
been run before:
This is getlino version 24.3.0 running on Ubuntu 22.04.4 LTS (ubuntu jammy).
This will write to configuration file /home/luc/.getlino.conf
Basically you just answer ENTER to every question, or y when ENTER doesn’t continue. Sometimes you can skip a step by answering n, for example when it asks to “run sudo apt-get update -y;sudo apt-get upgrade -y;” and you know that you did that recently.
You will also see that the answer to the question about repos_base is set to what you specified at the command-line:
- repos_base (Base directory for shared code repositories) [~/repositories]:
At some moment you should see:
Clone repositories to /home/luc/work ? [y or n] Yes
No need to clone atelier : directory exists.
No need to clone etgen : directory exists.
No need to clone eid : directory exists.
No need to clone cd : directory exists.
No need to clone getlino : directory exists.
No need to clone lino : directory exists.
No need to clone xl : directory exists.
No need to clone welfare : directory exists.
No need to clone react : directory exists.
No need to clone openui5 : directory exists.
No need to clone book : directory exists.
No need to clone cg : directory exists.
No need to clone ug : directory exists.
No need to clone hg : directory exists.
No need to clone lf : directory exists.
No need to clone ss : directory exists.
No need to clone algus : directory exists.
No need to clone amici : directory exists.
No need to clone avanti : directory exists.
No need to clone cms : directory exists.
No need to clone care : directory exists.
No need to clone cosi : directory exists.
No need to clone mentori : directory exists.
No need to clone noi : directory exists.
No need to clone presto : directory exists.
No need to clone pronto : directory exists.
No need to clone tera : directory exists.
No need to clone shop : directory exists.
No need to clone vilma : directory exists.
No need to clone voga : directory exists.
No need to clone weleup : directory exists.
No need to clone welcht : directory exists.
How to switch to the development version of atelier¶
This section is not needed and not much tested. Read and follow at your own risk.
The atelier
package had been automatically installed together
with lino
. That is, you are using the PyPI version of
Atelier. That’s usually okay because Atelier is more or less
stable. But one day we might decide that you should rather switch to
the development version.
Doing this is theoretically easy. Uninstall the PyPI version and then install the development version:
$ pip uninstall atelier
$ cd ~/lino/env/repositories
$ git clone https://github.com/lino-framework/atelier.git
$ pip install -e atelier
How to send emails from your developer environment¶
The demo sites of a developer environment don’t send any emails to the outside world. The test suite uses different techniques to simulate sending emails. But even as a Lino developer you might want to really send emails. For example when you develop or debug some action that sends emails and you want to really send them out. Or maybe you run your own production site on your developer machine.
The related Django settings (for example EMAIL_HOST_USER
and
EMAIL_HOST_PASSWORD
) contain information that only you can give. And
you don’t want to accidentally publish them. This is why you want to store them
in your local settings module.
Note that not all demo projects use the local
settings module. Only those which have the following lines in their
settings.py
file:
try:
from lino_local.settings import *
except ImportError:
pass
The local settings module¶
Your local settings module has been created by getlino configure
in file ~/lino/lino_local/settings.py
.
If you want Lino to find it, you need to set PYTHONPATH
to
~/lino
. For example by adding the following line to your
.bashrc
file:
export PYTHONPATH=/home/joe/lino
On a production server or for sites created with getlino
startsite
you don’t need to set PYTHONPATH
because the
manage.py
script of these sites contains a line sys.path.insert(0,
'/usr/local/lino')
.
Using the console email backend¶
Rather than actually sending out emails, you might prefer to simply see them on
the console. You can achieve this by setting EMAIL_BACKEND
as
follows:
EMAIL_BACKEND = 'django.core.mail.backends.console.EmailBackend'
With that setting you can copy the console output to a file tmp.eml
and
then opene this file in Thunderbird.