Changeset View
Changeset View
Standalone View
Standalone View
docs/developer-setup.rst
| .. _developer-setup: | .. _developer-setup: | ||||
| Developer setup | Developer setup | ||||
| =============== | =============== | ||||
| In this guide we describe how to set up a developer environment in which one | In this guide we describe how to set up a developer environment in which one | ||||
| can easily navigate the source code, make modifications, write and execute unit | can easily navigate the source code, make modifications, write and execute unit | ||||
| tests. | tests. | ||||
| For this, we will use a `virtualenv`_ in which all the |swh| packages will be | For this, we will use a `virtual environment`_ in which all the |swh| packages will be | ||||
| installed in 'develop' mode, this will allow you to navigate the source code, | installed in 'develop' mode, this will allow you to navigate the source code, | ||||
| hack it, and run locally the unit tests. | hack it, and run locally the unit tests. | ||||
| If you want to test the effect of your modifications in a running |swh| | To test the effect of your modifications, you can :ref:`install your own local | ||||
| instance, you should check the swh-environment docker `documentation`_. | Software Heritage instance <getting-started>` using Docker. | ||||
| .. _`documentation`: https://forge.softwareheritage.org/source/swh-environment/browse/master/docker/README.rst?as=remarkup | .. _`documentation`: https://forge.softwareheritage.org/source/swh-environment/browse/master/docker/README.rst?as=remarkup | ||||
| .. _`virtualenv`: https://pypi.org/project/virtualenv/ | .. _`virtual environment`: https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/#creating-a-virtual-environment | ||||
| Install required dependencies | Install required dependencies | ||||
| ----------------------------- | ----------------------------- | ||||
| Software Heritage requires some dependencies that are usually packaged by your | Software Heritage requires some dependencies that are usually packaged by your | ||||
| package manager. On Debian/Ubuntu-based distributions:: | package manager. On Debian/Ubuntu-based distributions:: | ||||
| Show All 12 Lines | sudo apt install \ | ||||
| postgresql-autodoc graphviz plantuml inkscape \ | postgresql-autodoc graphviz plantuml inkscape \ | ||||
| postgresql libpq-dev cassandra yarnpkg | postgresql libpq-dev cassandra yarnpkg | ||||
| .. Note:: Python 3.7 or newer is required | .. Note:: Python 3.7 or newer is required | ||||
| This installs basic system utilities, Python library dependencies, development tools, | This installs basic system utilities, Python library dependencies, development tools, | ||||
| documentation tools and our main database management systems. | documentation tools and our main database management systems. | ||||
| Cassandra and postgresql will be started by tests when they need it, so you | Cassandra and PostgreSQL will be started by tests when they need it, so you | ||||
| don't need them started globally (this will save you some RAM):: | don't need them started globally (this will save you some RAM):: | ||||
| sudo systemctl stop postgresql | sudo systemctl disable --now cassandra postgresql | ||||
vlorentz: neat | |||||
| sudo systemctl disable postgresql | |||||
| sudo systemctl stop cassandra | |||||
| sudo systemctl disable cassandra | |||||
| If you intend to hack on the frontend part of |swh| Web Applications, you will also | If you intend to hack on the frontend part of |swh| Web Applications, you will also | ||||
| need to have nodejs >= 14 in your development environment. If the version in your | need to have nodejs >= 14 in your development environment. If the version in your | ||||
| Debian-based distribution is lower, you can install node 14 using these commands:: | Debian-based distribution is lower, you can install node 14 using these commands:: | ||||
| sudo wget https://deb.nodesource.com/gpgkey/nodesource.gpg.key -O /etc/apt/trusted.gpg.d/nodesource.asc | sudo wget https://deb.nodesource.com/gpgkey/nodesource.gpg.key -O /etc/apt/trusted.gpg.d/nodesource.asc | ||||
| echo "deb https://deb.nodesource.com/node_14.x $(lsb_release -cs) main" | sudo tee -a /etc/apt/sources.list.d/nodesource.list | echo "deb https://deb.nodesource.com/node_14.x $(lsb_release -cs) main" | sudo tee -a /etc/apt/sources.list.d/nodesource.list | ||||
| sudo apt update | sudo apt update | ||||
| ▲ Show 20 Lines • Show All 189 Lines • ▼ Show 20 Lines | |||||
| Setup the databases (optional) | Setup the databases (optional) | ||||
| ------------------------------ | ------------------------------ | ||||
| If you want to run some packages manually, you may need to setup their databases. | If you want to run some packages manually, you may need to setup their databases. | ||||
| The different databases for each subproject that requires one (like ``storage`` or ``scheduler``) should be setup through the ``swh db create`` or ``swh db init`` command. See their help for more information. | The different databases for each subproject that requires one (like ``storage`` or ``scheduler``) should be setup through the ``swh db create`` or ``swh db init`` command. See their help for more information. | ||||
| Test changes using a local instance | |||||
| ----------------------------------- | |||||
| How to test your changes with a local instance is explained in the :ref:`documentation about our Docker setup <docker-environment>`. | |||||
| Sending your changes | Sending your changes | ||||
| -------------------- | -------------------- | ||||
| After you are done making the changes you want, you can send them on our | After you are done making the changes you want, you can send them on our | ||||
| forge_. The best way to do that is to use Arcanist, so we recommend you read | forge. See the guide on :ref:`how to submit patches <patch-submission>`. | ||||
| these two guides if you are not familiar with it: | |||||
| * https://wiki.softwareheritage.org/wiki/Arcanist_setup | |||||
| * https://wiki.softwareheritage.org/wiki/Code_review_in_Phabricator | |||||
| .. _pytest: https://pytest.org | .. _pytest: https://pytest.org | ||||
| .. _tox: https://tox.readthedocs.io | .. _tox: https://tox.readthedocs.io | ||||
| .. _pypi: https://pypi.org | .. _pypi: https://pypi.org | ||||
| .. _swh-loader-git: https://forge.softwareheritage.org/source/swh-loader-git | .. _swh-loader-git: https://forge.softwareheritage.org/source/swh-loader-git | ||||
| .. _pifpaf: https://github.com/jd/pifpaf | .. _pifpaf: https://github.com/jd/pifpaf | ||||
| .. _forge: https://forge.softwareheritage.org/ | |||||
neat