diff --git a/buildslave.rst b/buildslave.rst new file mode 100644 --- /dev/null +++ b/buildslave.rst @@ -0,0 +1,100 @@ +.. _buildslave: + +Running a Build Slave +===================== + +The build slaves are an essential part of the Python development +process (see the :doc:`continuous_integration` page). Running a build +slave is a great way to help the Python community. It's a good way to +help even if you don't have much programming experience. + +We need to add more platforms (and compilers!) to the Buildbot farm. If +you have one of these machines you are willing to run Buildbot on, +please contact python-dev@python.org: + +* Windows (see below) +* AIX +* HP-UX +* FreeBSD, NetBSD, OpenBSD +* Solaris / OpenSolaris / OpenIndiana / Illumos + +It might also be beneficial to run on older versions of operating +systems or others not mentioned above. Feel free to contact us if you +would like to offer another type of system. + +Running a build slave in a virtual machine is a common practice and a +good idea. It allows you to run more than one build slave (for +different operating systems) on the same physical computer. However, +there is no requirement that you run build slaves in virtual machines. + +Installing a Build Slave (Buildbot) +----------------------------------- + +Python core development uses `Buildbot `_ for +continuous integration. Installing a Buildbot slave requires three +things: + +* the standard CPython development toolchain (see the :doc:`setup` + page in this devguide), +* `Mercurial `_, +* a recent version of Buildbot. + +Here is a list of steps to do that last bit the easy way (as root): + +1. install Python 2.7 from source (again see that setup page), +2. install `pip `, +3. run 'pip install buildslave'. + +At this point someone will need to create a slavename/slavepasswd pair +on dinsdale.python.org. Ask on python-dev@python.org once you're ready. + +Once you have the credentials you are ready to create the actual build +slave. Follow these steps: + + $ su - buildbot + $ mkdir buildarea + $ buildslave create-slave $HOME/buildarea dinsdale.python.org:9020 + slavename slavepasswd + +Next, edit buildarea/info/admin and buildarea/info/host to set them +appropriately. + +Finally, start Buildbot (still under the 'buildbot' user) with: + + $ buildslave start $HOME/buildarea + +Once Buildbot is running, don't forget to monitor the build results +and solve any setup issues causing test failures. + +Buildbot on Windows +------------------- + +See the page at http://wiki.python.org/moin/BuildbotOnWindows. + +Use of Network Ports +-------------------- + +Running a build slave requires some network access. Here are the +inbound network ports that may be used on the host's public interface. +The only port that is actually required is 9020. + +The description column mostly refers to the tests in the suite that +need that port. If any one of the ports is not open, the test run +should skip the corresponding tests. Likewise, if any of those tests +are failing unexpectedly, make sure the corresponding port is open. + +========== ============================= =================================== +Port Host Description +========== ============================= =================================== +20, 21 ftp.kernel.org, ftp.mirror.nl test_urllib2net +53 your DNS server test_socket (and others implicitly) +80 python.org (several tests) +119 news.gmane.org test_nntplib +443 (various) test_ssl +465 smtp.gmail.com test_smtpnet +9020 python.org Buildbot connection +========== ============================= =================================== + +Many tests will also create local TCP sockets and connect to them +(usually through "localhost" or "127.0.0.1"), so make sure this +capability hasn't been disabled. diff --git a/buildbots.rst b/continuous_integration.rst rename from buildbots.rst rename to continuous_integration.rst --- a/buildbots.rst +++ b/continuous_integration.rst @@ -1,4 +1,4 @@ -.. _buildbots: +.. _continuous_integration: Continuous Integration ====================== @@ -23,6 +23,9 @@ important that you get acquainted with the way these results are presented, and how various kinds of failures can be explained and diagnosed. +.. note:: + See the :doc:`buildslave` page for more on setting up and running one. + Checking results of automatic builds ------------------------------------ diff --git a/index.rst b/index.rst --- a/index.rst +++ b/index.rst @@ -66,17 +66,18 @@ * :doc:`coverage` * Advanced tasks for once you are comfortable * :doc:`silencewarnings` - * Fixing issues found by the :doc:`buildbots ` + * Fixing issues found by the :doc:`buildbots ` * :doc:`fixingissues` * :doc:`helptriage` * :doc:`devrole` * :doc:`triaging` * :doc:`languishing` * :doc:`communication` +* :doc:`buildslave` * :doc:`coredev` * :doc:`committing` * :doc:`devcycle` - * :doc:`buildbots` + * :doc:`continuous_integration` It is **recommended** that the above documents be read in the order listed. You can stop where you feel comfortable and begin contributing immediately