Makefile Targets¶
With the aim to simplify development cycles, started with PR 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):
test - run developer tests
docs - build documentation
docs-live - autobuild HTML documentation while editing
run - run developer instance
install - developer install (./local)
uninstall - uninstall (./local)
gh-pages - build docs & deploy on gh-pages branch
clean - drop builds and environments
project - re-build generic files of the searx project
buildenv - re-build environment files (aka brand)
themes - re-build build the source of the themes
docker - build Docker image
node.env - download & install npm dependencies locally
environment
SEARX_URL = https://searx.me
GIT_URL = https://github.com/searx/searx
DOCS_URL = https://searx.github.io/searx
CONTACT_URL =
make V=0|1 [targets] 0 => quiet build (default), 1 => verbose build
make V=2 [targets] 2 => give reason for rebuild of target
to get more help: make help-all
Contents
Makefile setup¶
The main setup is done in the git://Makefile.
export GIT_URL=https://github.com/searx/searx
export GIT_BRANCH=master
export SEARX_URL=https://searx.me
export DOCS_URL=https://searx.github.io/searx
# export CONTACT_URL=mailto:contact@example.com
- 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¶
With Makefile we do no longer need to build up the virtualenv manually (as
described in the Development Quickstart 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 (git://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.
If you think, something goes wrong with your ./local environment or you change the git://setup.py file (or the requirements listed in git://requirements-dev.txt and git://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 git://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 Python environment.
$ 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 section. If you want to edit the documentation
read our live build section. If you are working in your own brand,
adjust your Makefile setup.
make books/{name}.html books/{name}.pdf¶
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 (git://docs/user/conf.py). Such conf.py
do inherit from git://docs/conf.py and overwrite values to fit book’s
needs.
With the help of Intersphinx (Smart refs) 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:
...
books/{name}.html : build only the HTML of document {name}
valid values for books/{name}.html are:
books/user.html
books/{name}.pdf : build only the PDF of document {name}
valid values for books/{name}.pdf are:
books/user.pdf
make gh-pages¶
To deploy on github.io first adjust your 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. 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 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 git://.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 PyPi: searx you will
never need the latter.
