This is a brief introduction to the internals of ToxicBuild for those who want to hack it in some way. ToxicBuild is written in python so you must have some python dev tools, like virtualenv-wrapper and C compiler and some header files to install it.
Installing from sources¶
Before we fetch the code, lets create a virtualenv to install our code inside.
$ mkvirtualenv toxicbuild -p python3.5 $ mkdir ~/hacks $ cd ~/hacks
Now you may clone the code from github:
$ git clone https://github.com/jucacrispim/toxicbuild.git $ cd toxicbuild
And now install the dependencies:
$ pip install -r requirements.txt
Finally, run the tests:
$ python setup.py test $ behave tests/functional/webui/
You should see no errors in the tests.
Setting up a development environment¶
In the user documentation we saw how to create a new environment using a code “installed” in your system (or venv). To hack the code is better to have an environment that is linked to your live code. This is what we are going to do now.
First, create a directory for our development environment and link everything that is needed:
$ mkdir ~/hacks/cienv $ cd ~/hacks/cienv $ ln -s ~/hacks/toxicbuild/toxicbuild toxicbuild $ ln -s ~/hacks/toxicbuild/script/toxicmaster ~/hacks/cienv/toxicmaster $ ln -s ~/hacks/toxicbuild/script/toxicslave ~/hacks/cienv/toxicslave $ ln -s ~/hacks/toxicbuild/script/toxicweb ~/hacks/cienv/toxicweb
When everything is ready we can start the componets needed to have a functional toxicbuild environment:
$ ~/hacks/toxicbuild/toxicslave start ~/hacks/cienv/slave --daemonize --loglevel=debug $ ~/hacks/toxicbuild/toxicmaster start ~/hacks/cienv/master --daemonize --loglevel=debug $ ~/hacks/toxicbuild/toxicweb start ~/hacks/cienv/ui --daemonize --loglevel=debug
How that works¶
ToxicBuild consists in three parts: master, slave and ui. Each componet talks to the others they need using the ToxicBuild Poor’s Protocol.
In the users’ guide we saw how to start the whole thing at once using the
toxicbuild command. We may start each one of the components individually
toxicweb command. Use them
-h option for more information.
The master is resposible for polling data (
from the repositories (
toxicbuild.master.repository), notifying the
slaves about new builds and send information about builds to the ui(s). Clients
communicate to the master, asking for things, like to add a new repo, start a
build or listen to events that occour in the master throught the
toxicbuild.master.hole (using the tpp, of course.)
It also has some plugins (
toxicbuild.master.plugins) that are, at the
moment, used to send information about builds to different places, like e-mail
notification or integration with 3rd party systems like slack.
Slaves are responsible for actually carrying the builds, executing the steps. They receive build requests from the master, execute the builds and send iformation about these builds back to the master. Slaves also have plugins. Slave plugins add steps before and/or after the steps defined by you in your toxicbuild.conf file.
Writting slave plugins¶
To write slave plugins you must extend
toxicbuild.slave.plugins.SlavePlugin. You may implement the methods
get_steps_before() that adds steps before the steps created by you in
get_steps_after() that adds steps after the steps created
by you and
get_env_vars() that adds environment variables to all steps
of your build.