searxng/docs/dev/makefile.rst

Makefile Targets

build environment

Before looking deeper at the targets, first read about makefile setup and make pyenv.

To install system requirements follow buildhosts.

With the aim to simplify development cycles, started with 1756 a Makefile based boilerplate was added. If you are not familiar with Makefiles, we recommend to read gnu-make introduction.

The usage is simple, just type make {target-name} to build a target. Calling the help target gives a first overview (make help):

bash -c "cd ..; make --no-print-directory help"

Contents

Makefile setup

fork & upstream

Commit changes in your (local) branch, fork or whatever, but do not push them upstream / git stash is your friend.

The main setup is done in the Makefile.

../../Makefile

GIT_URL

Changes this, to point to your searx fork.

GIT_BRANCH

Changes this, to point to your searx branch.

SEARX_URL

Changes this, to point to your searx instance.

DOCS_URL

If you host your own (brand) documentation, change this URL.

If you change any of this build environment variables, you have to run make buildenv:

$ make buildenv
build searx/brand.py
build utils/brand.env

Python environment

activate environment

source ./local/py3/bin/activate

With Makefile we do no longer need to build up the virtualenv manually (as described in the devquickstart guide). Jump into your git working tree and release a make pyenv:

$ cd ~/searx-clone
$ make pyenv
PYENV     usage: source ./local/py3/bin/activate
...

With target pyenv a development environment (aka virtualenv) was build up in ./local/py3/. To make a developer install of searx (setup.py) into this environment, use make target install:

$ make install
PYENV     usage: source ./local/py3/bin/activate
PYENV     using virtualenv from ./local/py3
PYENV     install .

You have never to think about intermediate targets like pyenv or install, the Makefile chains them as requisites. Just run your main target.

drop environment

To get rid of the existing environment before re-build use clean target <make clean> first.

If you think, something goes wrong with your ./local environment or you change the setup.py file (or the requirements listed in requirements-dev.txt and requirements.txt), you have to call make clean.

make run

To get up a running a developer instance simply call make run. This enables debug option in searx/settings.yml, starts a ./searx/webapp.py instance, disables debug option again and opens the URL in your favorite WEB browser (xdg-open):

$ make run
PYENV     usage: source ./local/py3/bin/activate
PYENV     install .
./local/py3/bin/python ./searx/webapp.py
...
INFO:werkzeug: * Running on http://127.0.0.1:8888/ (Press CTRL+C to quit)
...

make clean

Drop all intermediate files, all builds, but keep sources untouched. Includes target pyclean which drops ./local environment. Before calling make clean stop all processes using make pyenv.

$ make clean
CLEAN     pyclean
CLEAN     clean

make docs docs-live docs-clean

We describe the usage of the doc* targets in the How to contribute / Documentation <contrib docs> section. If you want to edit the documentation read our make docs-live section. If you are working in your own brand, adjust your Makefile setup <makefile setup>.

make books/{name}.html books/{name}.pdf

info

To build PDF a XeTeX is needed, see buildhosts.

The books/{name}.* targets are building books. A book is a sub-directory containing a conf.py file. One example is the user handbook which can deployed separately (docs/user/conf.py). Such conf.py do inherit from docs/conf.py and overwrite values to fit book's needs.

With the help of Intersphinx (reST smart ref) the links to searx’s documentation outside of the book will be bound by the object inventory of DOCS_URL. Take into account that URLs will be picked from the inventary at documentation's build time.

Use make docs-help to see which books available:

bash -c "cd ..; make --no-print-directory docs-help"

make gh-pages

To deploy on github.io first adjust your Makefile setup <makefile setup>. For any further read deploy on github.io.

make test

Runs a series of tests: test.pep8, test.unit, test.robot and does additional pylint checks <make pylint>. You can run tests selective, e.g.:

$ make test.pep8 test.unit test.sh
. ./local/py3/bin/activate; ./manage.sh pep8_check
[!] Running pep8 check
. ./local/py3/bin/activate; ./manage.sh unit_tests
[!] Running unit tests

make pylint

Before commiting its recommend to do some (more) linting. Pylint is known as one of the best source-code, bug and quality checker for the Python programming language. Pylint is not yet a quality gate within our searx project (like test.pep8 <make test> it is), but Pylint can help to improve code quality anyway. The pylint profile we use at searx project is found in project's root folder .pylintrc.

Code quality is a ongoing process. Don't try to fix all messages from Pylint, run Pylint and check if your changed lines are bringing up new messages. If so, fix it. By this, code quality gets incremental better and if there comes the day, the linting is balanced out, we might decide to add Pylint as a quality gate.

make pybuild

Build Python packages in ./dist/py.

$ make pybuild
...
BUILD     pybuild
running sdist
running egg_info
...
$ ls  ./dist/py/
searx-0.15.0-py3-none-any.whl  searx-0.15.0.tar.gz

To upload packages to PyPi, there is also a upload-pypi target. It needs twine to be installed. Since you are not the owner of searx you will never need the latter.