README_BUILDSLAVE

How to setup a buildslave for PyPy
==================================

There are three documented ways to run a PyPy buildslave:

- "bare metal" on the host machine, described below
- in a chroot, setting up the chroot is described in `README-CHROOT`
- via docker on a centos7-based image, see docker/Dockerfile

In all cases the required setup is::
- hg
- "python" should run a python 2.7 that will run the test suites.
  This should be pypy2.7 on windows to prevent problems with mixing runtimes,
  (cpython is built with an ancient MSVC) but the buildbot itself requires
  pywin32 which is not supported, so you must use cpython on windows to run the
  buildbot. One way to have python.exe be an alias to pypy.exe is to create a
  PyPy2 virtual env and copy pypy.exe to python.exe. But now how can you run
  the buildbot? Create a CPython virtualenv, rename the python.exe in it to
  "python_for_buildbot" and run the buildbot with "python_for_buildbot.exe 
  buildslave start"
- virtualenv that will use the "python" from above
- pytest, hypothesis, pathlib, cffi pexpect for testing
- all the build dependencies list here
  http://doc.pypy.org/en/latest/build.html#install-build-time-dependencies

If your slave will be translating, you will also need
- pypy in your path
- at least 4GB of RAM for 32 bit, 6GB for 64 bit translations

On MacOS, you will need to use CPython2.7.16+ in order to download and build
the xz package since it requires a modern SSL.

On windows, you will need to add `externals/bin` to your PATH before running
the buildslave.

Then you will need to install the ``buildbot-slave`` package (pinning automat
for python2), which will install many other packages like twisted, so you may
prefer to run the slave in a virtualenv::

    pip install pytest hypothesis==4.42 cffi mercurial==6.1 virtualenv pexpect vmprof
    pip install buildbot-slave automat==20.2

The next step is to create a buildslave configuration file. Based on version
0.8.7 of buildbot you need to execute the following command.

buildslave create-slave  BASEDIR MASTERHOST:PORT SLAVENAME PASSWORD

The MASTERHOST currently is ``buildbot.pypy.org``. The
value for PORT is ``10407``.
SLAVENAME and PASSWORD can be freely chosen. These values need to be added to
the slaveinfo.py configuration file on the MASTERHOST, ask in the IRC channel
(#pypy on irc.libera.chat) for the settings to be added. BASEDIR is a path to a
local directory that will be created to contain all the files will be used by
the buildslave. 

Finally you will need to update the buildmaster configuration found in
https://foss.heptapod.net/pypy/buildbot/src/default/bot2/pypybuildbot/master.py
to associate the buildslave with one or more
builders. Builders define what tasks should be executed on the buildslave. 
Once the changes are commited the buildmaster on MASTERHOST needs to be updated
and restared to reflect the changes to the configuration.

Starting and stopping the buildslave
====================================

To start the buildslave just run

    buildslave start BASEDIR

and to stop it run

    buildslave stop BASEDIR