git.iko.soy/searx
on 5fc17de help sign in
searx/docs/dev/quickstart.rst
132 lines 3.3 kB history raw
1.. _devquickstart:
3======================
4Development Quickstart
5======================
7.. sidebar:: :ref:`makefile`
9 For additional developer purpose there are :ref:`makefile`.
11This quickstart guide gets your environment set up with searx. Furthermore, it
12gives a short introduction to the ``manage.sh`` script.
14How to setup your development environment
15=========================================
17.. sidebar:: :ref:`make pyenv <make pyenv>`
19 Alternatively use the :ref:`make pyenv`.
21First, clone the source code of searx to the desired folder. In this case the
22source is cloned to ``~/myprojects/searx``. Then create and activate the
23searx-ve virtualenv and install the required packages using ``manage.sh``.
25.. code:: sh
27 cd ~/myprojects
28 git clone https://github.com/asciimoo/searx.git
29 cd searx
30 python3 -m venv searx-ve
31 . ./searx-ve/bin/activate
32 ./manage.sh update_dev_packages
35How to run tests
36================
38.. sidebar:: :ref:`make test.unit <make test>`
40 Alternatively use the ``test.pep8``, ``test.unit``, ``test.robot`` targets.
42Tests can be run using the ``manage.sh`` script. Following tests and checks are
43available:
45- Unit tests
46- Selenium tests
47- PEP8 validation
48- Unit test coverage check
50For example unit tests are run with the command below:
52.. code:: sh
54 ./manage.sh unit_tests
56For further test options, please consult the help of the ``manage.sh`` script or
57read :ref:`make test`.
60How to compile styles and javascript
61====================================
63.. _less: http://lesscss.org/
64.. _NodeJS: https://nodejs.org
66How to build styles
67-------------------
69Less_ is required to build the styles of searx. Less_ can be installed using
70either NodeJS_ or Apt.
72.. code:: sh
74 sudo -H apt-get install nodejs
75 sudo -H npm install -g less
77OR
79.. code:: sh
81 sudo -H apt-get install node-less
83After satisfying the requirements styles can be build using ``manage.sh``
85.. code:: sh
87 ./manage.sh styles
90How to build the source of the themes
91=====================================
93.. _grunt: https://gruntjs.com/
95Grunt_ must be installed in order to build the javascript sources. It depends on
96NodeJS, so first Node has to be installed.
98.. code:: sh
100 sudo -H apt-get install nodejs
101 make node.env
103After installing grunt, the files can be built using the following command:
105.. code:: sh
107 make themes
110Tips for debugging/development
111==============================
113.. sidebar:: :ref:`make run`
115 Makefile target ``run`` already enables debug option for your developer
116 session / see :ref:`make run`.
118Turn on debug logging
119 Whether you are working on a new engine or trying to eliminate a bug, it is
120 always a good idea to turn on debug logging. When debug logging is enabled a
121 stack trace appears, instead of the cryptic ``Internal Server Error``
122 message. It can be turned on by setting ``debug: False`` to ``debug: True`` in
123 :origin:`settings.yml <searx/settings.yml>`.
125.. sidebar:: :ref:`make test`
127 Alternatively use the :ref:`make test` targets.
129Run ``./manage.sh tests`` before creating a PR.
130 Failing build on Travis is common because of PEP8 checks. So a new commit
131 must be created containing these format fixes. This phase can be skipped if
132 ``./manage.sh tests`` is run locally before creating a PR.