mirror of
https://github.com/odoo/documentation.git
synced 2026-01-02 17:59:20 +07:00
[MOV] howto/rdtraining: move "Getting started" to the tutorials dir
This commit also replaces references to the "Building a module" tutorial by references to the "Getting started" tutorial. task-2991663 Part-of: odoo/documentation#3655
This commit is contained in:
Antoine Vandevenne (anv)
380
content/developer/tutorials/getting_started/02_setup.rst
Normal file
380
content/developer/tutorials/getting_started/02_setup.rst
Normal file
@@ -0,0 +1,380 @@
|
||||
========================================
|
||||
Chapter 2: Development environment setup
|
||||
========================================
|
||||
|
||||
Depending on the intended use case, there are multiple ways to install Odoo. This tutorial will
|
||||
stick to the :ref:`source install <setup/install/source>` (:dfn:`running Odoo from the source
|
||||
code`), which is best suited for Odoo developers.
|
||||
|
||||
Throughout this document, we assume that you are installing your development environment on a
|
||||
laptop provided by Odoo with Linux Mint installed and up-to-date. If that is not the case, switch to
|
||||
the :guilabel:`Windows` or :guilabel:`Mac OS` tab if any section of the installation guide,
|
||||
depending on which OS you are on. The steps remain essentially the same.
|
||||
|
||||
Set up Git
|
||||
==========
|
||||
|
||||
Install and configure Git
|
||||
-------------------------
|
||||
|
||||
The very first step of the installation process is to install the `Git version control system
|
||||
<https://git-scm.com/>`_ because the Odoo source code is managed on `GitHub <https://github.com/>`_.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ sudo apt install git
|
||||
|
||||
.. tip::
|
||||
Check if Git is installed by trying to print Git's version with the following command:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ git --version
|
||||
|
||||
Once installed, register your name and email:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ git config --global user.name "Your full name (trigram)"
|
||||
$ git config --global user.email "xyz@odoo.com"
|
||||
|
||||
Configure GitHub
|
||||
----------------
|
||||
|
||||
You need a GitHub account to fetch the sources and contribute to Odoo's development. If you don't
|
||||
have one yet, create it. For the username, we recommend using your trigram "xyz" (or quadrigam)
|
||||
followed by '-odoo': 'xyz-odoo'.
|
||||
|
||||
The easiest way to authenticate with GitHub is to use an SSH connection. Using SSH authentication
|
||||
allows you to connect to GitHub without supplying your username and password every time you type a
|
||||
command.
|
||||
|
||||
.. note::
|
||||
The following step-by-step procedure is based on the `official GitHub documentation
|
||||
<https://docs.github.com/en/authentication/connecting-to-github-with-ssh>`_.
|
||||
|
||||
#. Generate a new SSH key, add it to the ssh-agent, and copy the SSH key to your clipboard.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ ssh-keygen -t ed25519 -C "xyz@odoo.com"
|
||||
$ ssh-add ~/.ssh/id_ed25519
|
||||
$ sudo apt install xclip
|
||||
$ xclip -sel clip < ~/.ssh/id_ed25519.pub
|
||||
|
||||
#. Go to `GitHub.com <https://github.com/>`_, then click on your profile picture in the upper-right
|
||||
corner of the page and then on :guilabel:`Settings`.
|
||||
|
||||
.. image:: 02_setup/account-settings.png
|
||||
|
||||
#. On the user settings sidebar, click on :guilabel:`SSH and GPG keys`.
|
||||
|
||||
.. image:: 02_setup/settings-sidebar-ssh-keys.png
|
||||
|
||||
#. Click on :guilabel:`New SSH key` or on :guilabel:`Add SSH key`.
|
||||
|
||||
.. image:: 02_setup/ssh-add-ssh-key.png
|
||||
|
||||
#. In the :guilabel:`Title` field, add a descriptive label for the new key.
|
||||
#. Paste your key into the :guilabel:`Key` field.
|
||||
|
||||
.. image:: 02_setup/ssh-key-paste.png
|
||||
|
||||
#. Click on :guilabel:`Add SSH key`.
|
||||
|
||||
Fetch the sources
|
||||
=================
|
||||
|
||||
It is time to fetch the source code of Odoo. First, let's create a home for the Git repositories in
|
||||
:file:`$HOME/src/`.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ mkdir -p $HOME/src
|
||||
$ cd $HOME/src
|
||||
|
||||
Then, clone the two repositories with SSH as explained in the :ref:`Installing Odoo guide
|
||||
<setup/install/source/git>`.
|
||||
|
||||
.. tip::
|
||||
Cloning the repositories will take a while, enjoy a cup of coffee while you wait.
|
||||
|
||||
.. _tutorials/getting_started/02_setup/development_repository:
|
||||
|
||||
Configure the Git repositories
|
||||
==============================
|
||||
|
||||
To contribute to an Odoo repository, you first need to `fork it
|
||||
<https://docs.github.com/en/get-started/quickstart/contributing-to-projects>`_, then create a branch
|
||||
containing your changes on the fork, and finally submit a `Pull Request
|
||||
<https://docs.github.com/en/get-started/quickstart/github-glossary#pull-request>`_ to the
|
||||
repository.
|
||||
|
||||
.. tip::
|
||||
If you are lucky enough to work at Odoo, the forks already exist. They are hosted on
|
||||
https://github.com/odoo-dev/odoo and https://github.com/odoo-dev/enterprise.
|
||||
|
||||
After your two forks are created, their remote address can be added in your local repositories. In
|
||||
the commands below, replace `odoo-dev/odoo` and `odoo-dev/enterprise` with the name of your forks if
|
||||
needed.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ cd $HOME/src/odoo
|
||||
$ git remote add odoo-dev git@github.com:odoo-dev/odoo.git # Add odoo-dev as a new remote.
|
||||
$ git remote rename origin odoo # Change the name of origin (the odoo repository) to odoo.
|
||||
$ git remote set-url --push odoo no_push # Remove the possibility to push directly to odoo (you can only push to odoo-dev).
|
||||
|
||||
$ cd $HOME/src/enterprise
|
||||
$ git remote add enterprise-dev git@github.com:odoo-dev/enterprise.git
|
||||
$ git remote rename origin enterprise
|
||||
$ git remote set-url --push enterprise no_push
|
||||
|
||||
Install the dependencies
|
||||
========================
|
||||
|
||||
As seen in :ref:`tutorials/getting_started/01_architecture`, Odoo's server runs on Python and uses
|
||||
PostgreSQL as an RDBMS. In the context of a development machine, the easiest approach is to install
|
||||
everything locally. To do so, follow once again the :ref:`Installing Odoo guide
|
||||
<setup/install/source/prepare>`.
|
||||
|
||||
.. tip::
|
||||
Some useful SQL commands:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ createdb $DB_NAME # Create a database.
|
||||
$ dropdb $DB_NAME # Drop a database.
|
||||
|
||||
$ psql $DB_NAME # Connect to a database.
|
||||
\l #List all the available databases.
|
||||
\dt #List all the tables of the $DB_NAME database.
|
||||
\d $TABLE_NAME #Show the structure of the table $TABLE_NAME.
|
||||
\q #Quit the psql environment (ctrl + d).
|
||||
|
||||
Run the server
|
||||
==============
|
||||
|
||||
Launch with `odoo-bin`
|
||||
----------------------
|
||||
|
||||
Once all dependencies are set up, Odoo can be launched by running `odoo-bin`, the command-line
|
||||
interface of the server.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ cd $HOME/src/odoo/
|
||||
$ ./odoo-bin --addons-path="addons/,../enterprise/" -d rd-demo
|
||||
|
||||
There are multiple :ref:`command-line arguments <reference/cmdline/server>` that you can use to run
|
||||
the server. In this training you will only need some of them.
|
||||
|
||||
.. option:: -d <database>
|
||||
|
||||
The database that is going to be used.
|
||||
|
||||
.. option:: --addons-path <directories>
|
||||
|
||||
A comma-separated list of directories in which modules are stored. These directories are scanned
|
||||
for modules.
|
||||
|
||||
.. option:: --limit-time-cpu <limit>
|
||||
|
||||
Prevent the worker from using more than <limit> CPU seconds for each request.
|
||||
|
||||
.. option:: --limit-time-real <limit>
|
||||
|
||||
Prevent the worker from taking longer than <limit> seconds to process a request.
|
||||
|
||||
.. tip::
|
||||
- The :option:`--limit-time-cpu` and :option:`--limit-time-real` arguments can be used to prevent
|
||||
the worker from being killed when debugging the source code.
|
||||
- | You may face an error similar to `AttributeError: module '<MODULE_NAME>' has no attribute
|
||||
'<$ATTRIBUTE'>`. In this case, you may need to re-install the module with :command:`$ pip
|
||||
install --upgrade --force-reinstall <MODULE_NAME>`.
|
||||
| If this error occurs with more than one module, you may need to re-install all the
|
||||
requirements with :command:`$ pip install --upgrade --force-reinstall -r requirements.txt`.
|
||||
| You can also clear the python cache to solve the issue:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ cd $HOME/.local/lib/python3.8/site-packages/
|
||||
$ find -name '*.pyc' -type f -delete
|
||||
|
||||
- Other commonly used arguments are:
|
||||
|
||||
- :option:`-i <odoo-bin --init>`: Install some modules before running the server
|
||||
(comma-separated list).
|
||||
- :option:`-u <odoo-bin --update>`: Update some modules before running the server
|
||||
(comma-separated list).
|
||||
|
||||
Log in to Odoo
|
||||
--------------
|
||||
|
||||
Open http://localhost:8069/ on your browser. We recommend using `Chrome
|
||||
<https://www.google.com/intl/en/chrome/>`_, `Firefox <https://www.mozilla.org/firefox/new/>`_, or
|
||||
any other browser with development tools.
|
||||
|
||||
To log in as the administrator user, use the following credentials:
|
||||
|
||||
- email: `admin`
|
||||
- password: `admin`
|
||||
|
||||
Enable the developer mode
|
||||
=========================
|
||||
|
||||
The developer or debug mode is useful for training as it gives access to additional (advanced)
|
||||
tools. In the next chapters, **we will always assume that you have enabled the developer mode**.
|
||||
|
||||
:ref:`Enable the developer mode <developer-mode>` now. Choose the method that you prefer; they are
|
||||
all equivalent.
|
||||
|
||||
.. note::
|
||||
The main page of the Settings screen is only accessible if at least one application is installed.
|
||||
You will be led into installing your own application in the next chapter.
|
||||
|
||||
Extra tools
|
||||
===========
|
||||
|
||||
Useful Git commands
|
||||
-------------------
|
||||
|
||||
Here are some useful Git commands for your day-to-day work.
|
||||
|
||||
- | Switch branches:
|
||||
| When you switch branches, both repositories (odoo and enterprise) must be synchronized, i.e.
|
||||
both need to be in the same branch.
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ cd $HOME/src/odoo
|
||||
$ git switch {BRANCH}
|
||||
|
||||
$ cd $HOME/src/enterprise
|
||||
$ git switch {BRANCH}
|
||||
|
||||
- Fetch and rebase:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
$ cd $HOME/src/odoo
|
||||
$ git fetch --all --prune
|
||||
$ git rebase --autostash odoo/{BRANCH}
|
||||
|
||||
$ cd $HOME/src/enterprise
|
||||
$ git fetch --all --prune
|
||||
$ git rebase --autostash enterprise/{BRANCH}
|
||||
|
||||
Code Editor
|
||||
-----------
|
||||
|
||||
If you are working at Odoo, many of your colleagues are using `VSCode
|
||||
<https://code.visualstudio.com>`_, `VSCodium <https://vscodium.com>`_ (the open source equivalent),
|
||||
`PyCharm <https://www.jetbrains.com/pycharm/download/#section=linux>`_, or `Sublime Text
|
||||
<https://www.sublimetext.com>`_. However, you are free to choose your preferred editor.
|
||||
|
||||
It is important to configure your linters correctly. Using a linter helps you by showing syntax and
|
||||
semantic warnings or errors. Odoo source code tries to respect Python's and JavaScript's standards,
|
||||
but some of them can be ignored.
|
||||
|
||||
For Python, we use PEP8 with these options ignored:
|
||||
|
||||
- `E501`: line too long
|
||||
- `E301`: expected 1 blank line, found 0
|
||||
- `E302`: expected 2 blank lines, found 1
|
||||
|
||||
For JavaScript, we use ESLint and you can find a `configuration file example here
|
||||
<https://github.com/odoo/odoo/wiki/Javascript-coding-guidelines#use-a-linter>`_.
|
||||
|
||||
Administrator tools for PostgreSQL
|
||||
----------------------------------
|
||||
|
||||
You can manage your PostgreSQL databases using the command line as demonstrated earlier or using
|
||||
a GUI application such as `pgAdmin <https://www.pgadmin.org/download/pgadmin-4-apt/>`_ or `DBeaver
|
||||
<https://dbeaver.io/>`_.
|
||||
|
||||
To connect the GUI application to your database we recommend you connect using the Unix socket.
|
||||
|
||||
- Host name/address: `/var/run/postgresql`
|
||||
- Port: `5432`
|
||||
- Username: `$USER`
|
||||
|
||||
Python Debugging
|
||||
----------------
|
||||
|
||||
When facing a bug or trying to understand how the code works, simply printing things out can go a
|
||||
long way, but a proper debugger can save a lot of time.
|
||||
|
||||
You can use a classic Python library debugger (`pdb <https://docs.python.org/3/library/pdb.html>`_,
|
||||
`pudb <https://pypi.org/project/pudb/>`_ or `ipdb <https://pypi.org/project/ipdb/>`_), or you can
|
||||
use your editor's debugger.
|
||||
|
||||
In the following example we use ipdb, but the process is similar with other libraries.
|
||||
|
||||
#. Install the library:
|
||||
|
||||
.. code-block:: console
|
||||
|
||||
pip install ipdb
|
||||
|
||||
#. Place a trigger (breakpoint):
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
import ipdb; ipdb.set_trace()
|
||||
|
||||
.. example::
|
||||
|
||||
.. code-block:: python
|
||||
:emphasize-lines: 2
|
||||
|
||||
def copy(self, default=None):
|
||||
import ipdb; ipdb.set_trace()
|
||||
self.ensure_one()
|
||||
chosen_name = default.get('name') if default else ''
|
||||
new_name = chosen_name or _('%s (copy)') % self.name
|
||||
default = dict(default or {}, name=new_name)
|
||||
return super(Partner, self).copy(default)
|
||||
|
||||
Here is a list of commands:
|
||||
|
||||
.. option:: h(elp) [command]
|
||||
|
||||
Print the list of available commands if not argument is supplied. With a command as an argument,
|
||||
print the help about that command.
|
||||
|
||||
.. option:: pp expression
|
||||
|
||||
The value of the `expression` is pretty-printed using the `pprint` module.
|
||||
|
||||
.. option:: w(here)
|
||||
|
||||
Print a stack trace with the most recent frame at the bottom.
|
||||
|
||||
.. option:: d(own)
|
||||
|
||||
Move the current frame one level down in the stack trace (to a newer frame).
|
||||
|
||||
.. option:: u(p)
|
||||
|
||||
Move the current frame one level up in the stack trace (to an older frame).
|
||||
|
||||
.. option:: n(ext)
|
||||
|
||||
Continue the execution until the next line in the current function is reached or it returns.
|
||||
|
||||
.. option:: c(ontinue)
|
||||
|
||||
Continue the execution and only stop when a breakpoint is encountered.
|
||||
|
||||
.. option:: s(tep)
|
||||
|
||||
Execute the current line. Stop at the first possible occasion (either in a function that is
|
||||
called or on the next line in the current function).
|
||||
|
||||
.. option:: q(uit)
|
||||
|
||||
Quit the debugger. The program being executed is aborted.
|
||||
|
||||
Now that your server is running, it's time to start :ref:`writing your own application
|
||||
<tutorials/getting_started/03_newapp>`!
|
||||
Reference in New Issue
Block a user