Setting up your environment to automatically generate wxWidgets releases.

Contents

• Overview
• Software checklist
• Setting up sshd
• Configuring your environment
• Running the automated release system

Overview

The wxWidgets automated release system works by preparing a tarball of the CVS tree with the specified tag, then pushing that tag to the Windows, Linux and Mac build machines to perform the various steps required to create the tarballs, generate the docs, and perform test builds. In order for it to be able to do this, the release process needs to be broken up into two components:

• The build management machine, which we'll refer to as the MANAGER, that performs pre- and post-flight steps, monitors the builds for errors, keeps a running log of the various processes on the build machines, and halts the release process in case a fatal error has occurred.
• The build machines, which we'll call the BUILDERS, are accessed via sshd and perform the actual build steps. You will need 3 BUILDER machines - one Win box, one Linux box, and one Mac OS X box.

Note that for the purposes of this document, I will refer to the root wxWidgets source tree directory using the name wxSrc. So the readme file, for example, would be located at wxSrc/readme.txt.

Software checklist

On all platforms, you will need to have the following programs installed. Unless otherwise specified, the package is available from the OS vendor (or Cygwin on Windows).

On all machines:

• OpenSSH, for ssh and sshd
• make
• bash shell
• Cygwin (Windows)
• Apple Developer Tools (OS X)

On the MANAGER box:

• ReleaseForge (for uploading, announcing releases)
• Bakefile (if re-baking)
• scp/sftp
• Python 2.4 (should work with Python 2.3 too, but I've only tested against 2.4)
• TaskRunner (located in the wxPython/distrib/all dir)
• Cygwin if Win (MANAGER not yet tested on Windows box)

On BUILDERS:

• Tools necessary to build using the various compilers we support.
• Mac OS X needs to have unix2dos installed. You can get it from http://osxgnu.org.

On the doc building machine (Win only right now...):

• nmake
• HTML Help Workshop

NOTE: There is a script wxSrc/distrib/scripts/build-environ.sh which will install Bakefile, TaskRunner and ReleaseForge for you if you do not have them installed. Note you currently need to use this installer for ReleaseForge as it removes a bug with the command line mode upon install.

NOTE 2: You will also need to create C:\wx2dev and C:\transit directories on Win, and ~/wx2dev on Unix and Mac. In the future these dirs will probably be auto-created.

Once you have the required software installed, you will need to setup sshd on the 3 BUILDER boxes so that the MANAGER box can send files to them and send them commands. ssh is used to communicate between the MANAGER and BUILDERS.

Setting up sshd

Windows

You will need to setup sshd to run as a Windows XP process, which isn't too complicated but unfortunately takes a few more steps than setting *nix sshd. Instructions on how to do this can be found here:

http://lee.org/reading/computers/sshd/cygwin-sshd.html

Mac

The ability to run sshd is built into OS X (at least, on 10.3+). To turn it on, go to Apple menu->System Preferences. Then select "Sharing" and check the "Remote login" box.

Linux

I used Fedora Core 4 for my Linux box, and there sshd came with the system, and I simply needed to enable it from the Desktop->System Settings->Server Settings->Services dialog.

Enabling remote login via ssh

Once you've setup sshd on the BUILDERS, you will also need to create an ssh key on the MASTER build machine and distribute it to the BUILDERS. First, run ssh-keygen to create your public/private key on the MASTER build machine:

master@: ssh-keygen -t rsa

It will ask you if you want to use a passphrase. Usually, it is recommended that you create a passphrase, but if you don't want to enter a password when logging in (which you'll want for completely automated builds) and are behind a private network, just hit RETURN. This will create two files: ~/.ssh/id_rsa and ~/.ssh/id_rsa.pub. Then, the next step is to distribute the public key to the BUILDERS. To do this, run the following command:

scp ~/.ssh/id_rsa.pub <BUILDER_ALIAS_OR_IP>:~/.ssh/authorized_keys2

Once you copy the file over, you will be able to perform ssh and scp commands on the BUILDER without logging in. Note that if you are concerned about security, another way to handle the login is to create a passphrase and then use a tool such as ssh-agent to automatically log you in.

Configuring your environment

The only thing left to do before running the automated release system is to configure it to match your environment. There are two ways of doing this. First, you can modify the wxSrc/distrib/scripts/build-environ.cfg file and specify your own values. Second, you can create a ~/wxrelease-environ.cfg file and store your values there. (They will override the values loaded from build-environ.cfg.) Although I hope to further document the options later, necessary options and some documentation on them can be found by reading the wxSrc/distrib/scripts/build-environ.cfg file.

Running the automated release system

You should now be ready to run the automated release process. To start it, do the following (assumes you are using a terminal in the root wx directory):

cd distrib
python2.4 ./scripts/build_controller.py

Then, watch the build process move forward and do it's magic. If all goes well, the results should be placed in wxSrc/deliver on the MASTER build machine.