[Swift-devel] Example of a binary release build process from the OpenMX team

[Michael Wilde]

Attached is a note from Michael Spiegel on how they build OpenMx releases.  Just fyi.

OpenMx has a much harder job than us because they build binaries compiled for specific platforms. As a pure Java product, we avoid much of this.

But the attached doc has some release workflow examples that may be useful to us, including building the doc set and updating their web with a notice about the new release.

They dont automate this; we have I think some automation of our process but it needs to be dusted off, adjusted, and documented.

- Mike


----- Forwarded Message -----
From: "Michael Spiegel" <michael.m.spiegel at gmail.com>
To: "OpenMx Developers" <openmx-developers at list.mail.virginia.edu>
Sent: Tuesday, February 22, 2011 3:54:00 PM
Subject: [[openmx-dev]] binary release instructions

These instructions are primarily for Ross.  But I figured we should
keep a record of this information somewhere.  I do not recommend
attempting to automate this process, unless you are very good at
writing error handling routines for shell scripts.  Invariably,
something will go wrong in the build process.  When running this
process by hand, a person can stop and attempt to correct the problem.
 An automated script is likely to push the website into an
inconsistent state.

--Michael

-- 
Michael Wilde
Computation Institute, University of Chicago
Mathematics and Computer Science Division
Argonne National Laboratory

-------------- next part --------------
There are four possible build types when creating an OpenMx binary
release.  These four types are the cross-product of: (a) either building
a "dev" release from /trunk or a "stable" release from /tag. And (b) either
building the online documentation or not. Never lose track of which build 
type you currently creating. 

The following definitions are used in these notes:

SERVER = "openmx.psyc.virginia.edu"
SERVER_ROOT = "/var/openmx/newrelease"
SVN_REPO = either the "trunk" directory or a "tags/stable-XX" directory

I. On your local machine, we are run several tests on the code.
When the tests have passed, we will commit some changes to 
the svn repository that indicate a new binary version has been released.

- In SVN_REPO, run "make install".

- In SVN_REPO, run "make test".  Optionally use the CPUS=n argument.
  All these tests MUST PASS.

- In SVN_REPO, run "make check". Ignore the warning for missing documentation
  entires.  All other warnings must be corrected.

- Go to http://openmx.psyc.virginia.edu/dev/timeline. Let R* be the revision number
  in the top left panel.  The next revision number R = R* + 1. The full version number
  of a "dev" release is VERSION = 999.0.0-R.  The full version number of a stable release is
  VERSION = X.Y.Z-R.

- In SVN_REPO/Makefile, change the TARGET to OpenMx_[VERSION].tar.gz.
  In SVN_REPO/DESCRIPTION, change the "Version:" field and the "Date:" field.
  In SVN_REPO/CHANGES, rename the first line from "trunk" to "Release [VERSION] (Today's date)".
  In SVN_REPO/CHANGES, make sure to update the "=====" to the correct length.  That eliminates a warning message.
  If you are building the documentation, then in docs/source/conf.py update release and version information.

- Commit these changes to the SVN repository. Step (I) is completed.

II. ssh to SERVER and go to the directory SERVER_ROOT.  Run the script ./cleanup.sh.
    You are going to build the binary release on various machines.  For each build,
    you will copy the result into a subdirectory of SERVER_ROOT.  Each row of the following
    table has a hostname, a makefile target, the output file on the hostname, and the 
    destination directory on SERVER.

    hostname     make target    output file              destination directory

    euterpe      build32        build/OpenMx**.tar.gz    macosx-intel-32-2.12
    euterpe      build64        build/OpenMx**.tar.gz    macosx-intel-64-2.12
    euterpe      buildppc       build/OpenMx**.tar.gz    macosx-intel-ppc-2.12
    euterpe      srcbuild       build/OpenMx**.tar.gz    source
    euterpe      pdf            build/OpenMx.pdf         docs-api-pdf
    polymnia     build32        build/OpenMx**.tar.gz    macosx-intel-32-2.11
    polymnia     build64        build/OpenMx**.tar.gz    macosx-intel-64-2.11
    polymnia     buildppc       build/OpenMx**.tar.gz    macosx-intel-ppc-2.11
    win R 2.11   winbuild32     build/OpenMx**.tar.gz    windows-32-2.11
    win R 2.12   winbuild32     build/OpenMx**.tar.gz    windows-32-2.12
    
    You will need to rely on me to generate the windows builds until somebody else
    on the team procures a reasonable development machine that is running windows.

    If you are building the documentation, then first run "make html" on euterpe.
    Then enter the docs/ directory and run "make latex".  Finally enter the 
    docs/build/latex directory and run "make all-pdf".  You want to scp the file
    docs/build/latex/OpenMx.pdf into the destination directory "docs-userguide-pdf".
    You want to recursively copy all the contents of docs/build/html into the
    destination directory "docs-userguide-html".

    Now ssh into SERVER and go to SERVER_ROOT.  Type "ls -l *" to see that each directory
    has some files.  You want to edit the script "go.sh".  Change the version number
    to the correct version number of this binary release.  Next select the values you want for
    the TARGETDIR and MAKEDOCS variables.  Comment out the values you don't want.

    Run ./go.sh and see if any errors are reported.

    Finally, go to the website and test the installation of the binary release on your laptop.
    Then logon to the website and click on "Create Story" under "Publicist" in the left-hand panel.
    Create an announcement of the new binary release.  You may copy/paste the top of the CHANGES
    file into this annoucement.