searx/docs/dev/quickstart.rst

133 lines
3.3 KiB
ReStructuredText
Raw Normal View History

2016-04-21 13:15:04 +02:00
.. _devquickstart:
======================
2016-02-01 21:28:13 +01:00
Development Quickstart
======================
2016-02-01 21:28:13 +01:00
.. sidebar:: :ref:`makefile`
For additional developer purpose there are :ref:`makefile`.
This quickstart guide gets your environment set up with searx. Furthermore, it
gives a short introduction to the ``manage.sh`` script.
2016-02-01 21:28:13 +01:00
How to setup your development environment
=========================================
2016-02-01 21:28:13 +01:00
.. sidebar:: :ref:`make pyenv <make pyenv>`
Alternatively use the :ref:`make pyenv`.
First, clone the source code of searx to the desired folder. In this case the
source is cloned to ``~/myprojects/searx``. Then create and activate the
searx-ve virtualenv and install the required packages using ``manage.sh``.
2016-02-01 21:28:13 +01:00
.. code:: sh
cd ~/myprojects
git clone https://github.com/asciimoo/searx.git
cd searx
virtualenv searx-ve
. ./searx-ve/bin/activate
./manage.sh update_dev_packages
How to run tests
================
2016-02-01 21:28:13 +01:00
.. sidebar:: :ref:`make test.unit <make test>`
Alternatively use the ``test.pep8``, ``test.unit``, ``test.robot`` targets.
Tests can be run using the ``manage.sh`` script. Following tests and checks are
available:
2016-02-01 21:28:13 +01:00
- Unit tests
- Selenium tests
- PEP8 validation
- Unit test coverage check
For example unit tests are run with the command below:
.. code:: sh
./manage.sh unit_tests
2016-02-01 21:28:13 +01:00
For further test options, please consult the help of the ``manage.sh`` script or
read :ref:`make test`.
2016-02-01 21:28:13 +01:00
How to compile styles and javascript
====================================
.. _less: http://lesscss.org/
.. _NodeJS: https://nodejs.org
2016-02-01 21:28:13 +01:00
How to build styles
-------------------
2016-02-01 21:28:13 +01:00
Less_ is required to build the styles of searx. Less_ can be installed using
either NodeJS_ or Apt.
2016-02-01 21:28:13 +01:00
.. code:: sh
sudo -H apt-get install nodejs
sudo -H npm install -g less
2016-02-01 21:28:13 +01:00
OR
.. code:: sh
sudo -H apt-get install node-less
2016-02-01 21:28:13 +01:00
After satisfying the requirements styles can be build using ``manage.sh``
2016-02-01 21:28:13 +01:00
.. code:: sh
./manage.sh styles
2016-02-01 21:28:13 +01:00
How to build the source of the oscar theme
==========================================
2016-02-01 21:28:13 +01:00
.. _grunt: https://gruntjs.com/
Grunt_ must be installed in order to build the javascript sources. It depends on
NodeJS, so first Node has to be installed.
2016-02-01 21:28:13 +01:00
.. code:: sh
sudo -H apt-get install nodejs
sudo -H npm install -g grunt-cli
2016-02-01 21:28:13 +01:00
After installing grunt, the files can be built using the following command:
2016-02-01 21:28:13 +01:00
.. code:: sh
./manage.sh grunt_build
2016-04-21 13:15:04 +02:00
Tips for debugging/development
==============================
.. sidebar:: :ref:`make run`
Makefile target ``run`` already enables debug option for your developer
session / see :ref:`make run`.
Turn on debug logging
Whether you are working on a new engine or trying to eliminate a bug, it is
always a good idea to turn on debug logging. When debug logging is enabled a
stack trace appears, instead of the cryptic ``Internal Server Error``
message. It can be turned on by setting ``debug: False`` to ``debug: True`` in
:origin:`settings.yml <searx/settings.yml>`.
.. sidebar:: :ref:`make test`
Alternatively use the :ref:`make test` targets.
Run ``./manage.sh tests`` before creating a PR.
Failing build on Travis is common because of PEP8 checks. So a new commit
must be created containing these format fixes. This phase can be skipped if
``./manage.sh tests`` is run locally before creating a PR.