distrib/scripts/docs/creating_releases.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   4 <title>Untitled Document</title>
   5 </head>
   6
   7 <body>
   8 <p><font size="5"><b>Setting up your environment to automatically generate wxWidgets releases.</b></font></p>
   9 <p><b><font size="4">Contents</font></b></p>
  10 <ul>
  11   <li><a href="#overview">Overview</a></li>
  12   <li><a href="#checklist">Software checklist</a></li>
  13   <li><a href="#sshd">Setting up sshd</a></li>
  14   <li><a href="#configuring">Configuring your environment </a></li>
  15   <li><a href="#running">Running the  automated release system </a></li>
  16 </ul>
  17 <p><b><font size="4">Overview<a name="overview"></a></font></b></p>
  18 <p>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:</p>
  19 <ul>
  20   <li>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.</li>
  21   <li>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. </li>
  22 </ul>
  23 <p>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. </p>
  24 <p><b><font size="4">Software checklist </font></b><a name="checklist"></a></p>
  25 <p>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).</p>
  26 <p>On all machines:  </p>
  27 <ul>
  28   <li>OpenSSH, for ssh and sshd</li>
  29   <li>make</li>
  30   <li>bash shell   </li>
  31   <li>Cygwin (Windows) </li>
  32   <li>Apple Developer Tools (OS X) </li>
  33 </ul>
  34 <p>On the MANAGER box: </p>
  35 <ul>
  36   <li>ReleaseForge (for uploading, announcing releases) </li>
  37   <li>Bakefile (if re-baking) </li>
  38   <li>scp/sftp</li>
  39   <li>Python 2.4 (should work with Python 2.3 too, but I've only tested against 2.4) </li>
  40   <li>TaskRunner (located in the wxPython/distrib/all dir) </li>
  41   <li>Cygwin if Win (MANAGER not yet tested on Windows box) </li>
  42 </ul>
  43 <p>On BUILDERS:</p>
  44 <ul>
  45   <li>Tools necessary to build using the various compilers we support. </li>
  46   <li>Mac OS X needs to have unix2dos installed. You can get it from http://osxgnu.org.</li>
  47
  48   </ul>
  49 <p>On the doc building machine (Win only right now...):</p>
  50 <ul>
  51   <li>nmake</li>
  52   <li>HTML Help Workshop</li>
  53 </ul>
  54 <p><b>NOTE: </b>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.  </p>
  55 <p><b>NOTE 2: </b>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. </p>
  56 <p>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. </p>
  57 <p><b><font size="4">Setting up sshd </font></b><a name="sshd"></a></p>
  58 <p><b>Windows</b></p>
  59 <p>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: </p>
  60 <p><a href="http://lee.org/reading/computers/sshd/cygwin-sshd.html">http://lee.org/reading/computers/sshd/cygwin-sshd.html</a></p>
  61 <p><b>Mac</b> </p>
  62 <p>The ability to run sshd is built into OS X (at least, on 10.3+). To turn it on, go to Apple menu-&gt;System Preferences. Then select &quot;Sharing&quot; and check the &quot;Remote login&quot; box. </p>
  63 <p><b>Linux</b></p>
  64 <p>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-&gt;System Settings-&gt;Server Settings-&gt;Services dialog. </p>
  65 <p><b>Enabling remote login via ssh</b></p>
  66 <p>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:</p>
  67 <p>master@: ssh-keygen -t rsa</p>
  68 <p>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: </p>
  69 <p>scp ~/.ssh/id_rsa.pub &lt;BUILDER_ALIAS_OR_IP&gt;:~/.ssh/authorized_keys2</p>
  70 <p>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.  </p>
  71 <p><b><font size="4">Configuring your environment </font></b><a name="configuring"></a></p>
  72 <p>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. </p>
  73 <p><b><font size="4">Running the automated release system</font></b><a name="running"></a></p>
  74 <p>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):</p>
  75 <p>cd distrib<br>
  76   python2.4 ./scripts/build_controller.py</p>
  77 <p>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.  </p>
  78 <p>&nbsp;</p>
  79 <p>&nbsp; </p>
  80 </body>
  81 </html>