This Installation page works on the assumption that you have already submitted your [Exim BuildFarm Application](http://eximbuild.mrball.net/cgi-bin/register-form.pl) and the BuildFarm administration has sent you an email with your machine alias (aka _animal_) and secret password, which you will enter in step 9 below. If you just want to run the build farm client and never submit the results, you call simply run everything with the --test option and it will still work. If you ever run it without --test, it will still work, but the server will reject the feedback because it's from an unknown _animal_.
-If you want to run more than one instance of the build farm to test multiple different configurations, such as one with OpenSSL and one with GnuTLS, simply start at step 9. More details on the extra configuration required to keep it separate from the main build are at the end of this page.
+If you want to run more than one instance of the build farm to test multiple different configurations, such as one with OpenSSL and one with GnuTLS, for each subsequent animal simply start at step 9. More details on the extra configuration required to keep it separate from the main build are at the end of this page.
## Install Steps
1. Make sure that all required packages for Exim to build successfully are installed. The minimal package requirements are the basic suite of compiler tools and basic libraries. You will also need to install the ccache package.
10. Whatever directory is set as the *build_root* must exist before anything will run. If you didn't change it, this will be all that's needed:
`mkdir $HOME/buildfarm`
11. Directory permissions must be lax enough for the **exim** user running the test suite to be able to access the files that user farm has checked out. One recommendation that we know works is to make the **farm** user's home directory be both group and world readable and group and world searchable:
-`chmod og+rx $HOME`. Additionally, every subdirectory between */* and *$HOME/buildfarm* should have this permissive access.
+`chmod og+rx $HOME`. Additionally, every subdirectory between */* and *$HOME/buildfarm* should have this permissive access. One thing that these tighter permissions will break, for example, is test 0005, because the sudo'd exim process in the test suite will be unable to read that test config file.
12. Make sure that your umask is 0022: `umask 0022`. This also will need to be set in any script you call the run_build.pl script.
13. Test the configure process by running `./run_build.pl --test --verbose=2 --only-steps=configure`. If there are errors, you'll need to correct them until the process succeeds (ends with OK). You can repeat this as many times as necessary because test mode does not store the status of the git repo or the status of each stage of the build.
14. Test the build process by running `./run_build.pl --test --verbose=2 --only-steps=configure,make`. If there are build errors, make adjustments, install additional packages, etc, and repeat the test.
15. Test the test suite by running `./run_build.pl --test --verbose=2 --only-steps=configure,make,test --override range_num_tests='1 2'`. If there are build errors when building the test suite, or runtime errors trying to run the test suite, you may need to install additional packages (you shouldn't though).
-16. If you enabled the documentation building process in the *build-farm.conf*, then you can try to build it with `./run_build.pl --test --verbose=2 --only-steps=configure,make-doc`. For documentation generation to succeed, it will require extra packages to be installed to support xml, xslt, pdf, and a few other things.
+16. If you enabled the documentation building process in the *build-farm.conf*, then you can try to build it with `./run_build.pl --test --verbose=2 --only-steps=configure,make-doc`. For documentation generation to succeed, it will require extra packages to be installed to support xml, xslt, pdf, and a few other things. Please see the comments on the [Building Documentation](https://github.com/mrballcb/exim-build-farm-client/wiki/BuildingDocs) page.
17. If you can get past each of these steps, then your build farm system meets the minimum requirements.
18. The official process can be kicked off by running `/home/farm/code/run_cron.sh --run-all`. This will run the default build configuration, keep track of the git repository status, and upload the build results to the server.
19. Once that command runs with no complaints, add it to the **farm** user crontab. You can run it at whatever frequency you choose, I suggest 1 hour. If a previous instantiation is still running, the script will detect the lockfile and exit so as not to step on each other.
git://git.exim.org / buildfarm-client-wiki.git / blobdiff