/usr/share/mozart/doc/releasing/index.html is in mozart-doc 1.4.0-8ubuntu1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 | <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<HTML><HEAD><TITLE>The Secret Sucky Guide To Making Releases</TITLE><LINK href="ozdoc.css" rel="stylesheet" type="text/css"></HEAD><BODY><P class="margin"><A href="../index.html">Top</A><BR><A href="http://www.mozart-oz.org/download/view.cgi?action=print&class=misc&name=Releasing">Print</A></P><H1 align="center" class="title">The Secret Sucky Guide To Making Releases</H1><H2 align="center" class="authors"><A href="http://www.ps.uni-sb.de/~duchier/">Denys Duchier</A></H2><BLOCKQUOTE><P>This document explains how to create releases for various platforms. If you are a Mozart user interested in creating a binary distribution for your platform, you have two main options: </P><UL><LI><P>if your platform supports RPMs, then see how to create binary RPMs using our source RPM</P></LI><LI><P>otherwise, you should create binary tarballs.</P></LI></UL><P> Please, Please, Please: do contribute your binary distros back to us. This way, we can place them in our download area and everybody else can benefit from your effort. You do not need to bother with source and documentation distros, since our offerings for those are platform independent. If you are a Mozart release manager, see the last chapter which tells you all the steps you need to follow. </P></BLOCKQUOTE><HR><UL class="toc"><LI><A href="index.html#chap.intro">1 Introduction</A></LI><LI><A href="index.html#chap.tarballs">2 Tarballs</A><UL class="toc"><LI><A href="index.html#label1">2.1 Source Tarball</A></LI><LI><A href="index.html#label2">2.2 Documentation Tarball</A></LI><LI><A href="index.html#label3">2.3 Standard Library Tarball</A></LI><LI><A href="index.html#label4">2.4 Binary Tarballs</A><UL class="toc"><LI><A href="index.html#label5">2.4.1 Non-Linux Platforms</A><UL class="toc"><LI><A href="index.html#label6">Using Shared Object Libraries</A></LI><LI><A href="index.html#label7">Tcl/Tk</A></LI></UL></LI></UL></LI></UL></LI><LI><A href="index.html#label8">3 RPMs</A><UL class="toc"><LI><A href="index.html#label9">3.1 Binary RPMs</A></LI><LI><A href="index.html#label10">3.2 Source RPM</A></LI></UL></LI><LI><A href="index.html#label11">4 Check-List For Release Managers</A></LI></UL><HR><DIV id="chap.intro"><H1><A name="chap.intro">1 Introduction</A></H1><P>First, you need to download the sources. You can either download the source tarballs from our FTP server, or you can check out the sources directly from our CVS server.</P><P>Here is how to get the sources of a particular release from the Mozart CVS archive. A release is identified by a tag, e.g. <CODE>mozart-1-2-3</CODE>. In the following, I'll write <CODE>$<SPAN class="variablename">REL</SPAN></CODE> for the release tag. Use <CODE>ssh</CODE>, i. e. set environment variable <CODE><SPAN class="variablename">CVS_RSH</SPAN>=ssh</CODE>. </P><BLOCKQUOTE class="code"><CODE>cvs -d :pserver:anoncvs@cvs.mozart-oz.org:/services/mozart/CVS get -r $<SPAN class="variablename">REL</SPAN> mozart</CODE></BLOCKQUOTE><P> Get yourself a cup of coffee, and by the time you've savoured it you have become the proud owner of a copy of the Mozart sources. I will refer to the top directory containing these sources as <CODE>$<SPAN class="variablename">SOURCE</SPAN></CODE>: it is typically called <CODE>mozart</CODE> unless you used option <CODE>-d</CODE> to the CVS <CODE>get</CODE> command (which is unrelated to the <CODE>-d</CODE> option to the <CODE>cvs</CODE> command itself). It is highly recommended to also get a copy of the Mozart Standard Library: </P><BLOCKQUOTE class="code"><CODE>cvs -d :pserver:anoncvs@cvs.mozart-oz.org:/services/mozart/CVS get -r $<SPAN class="variablename">REL</SPAN> mozart-stdlib</CODE></BLOCKQUOTE><P> I will refer to the top directory containing the sources of the standard library as <CODE>$<SPAN class="variablename">STDLIB</SPAN></CODE>.</P><P>In order to build the release, you should create a separate build directory. I will call it <CODE>$<SPAN class="variablename">BUILD</SPAN></CODE> and it should not be created in <CODE>$<SPAN class="variablename">SOURCE</SPAN></CODE> tree. Simplest is to create it as a sibling of <CODE>$<SPAN class="variablename">SOURCE</SPAN></CODE>. Then you need to configure <CODE>$<SPAN class="variablename">BUILD</SPAN></CODE>: make very sure that no OZ utilities are found in your shell's search path and no OZ related variables are set in your environment. Personally, I have defined shell aliases <CODE>ozon</CODE> and <CODE>ozoff</CODE> to switch between having OZ utilities in my path and having a pristine environment blissfully unaware of things Mozartian. A minimally parametrized configuration would be: </P><BLOCKQUOTE class="code"><CODE><SPAN class="builtin">cd</SPAN> $<SPAN class="variablename">BUILD</SPAN> <BR>$<SPAN class="variablename">SOURCE</SPAN>/configure</CODE></BLOCKQUOTE><P> By default, this will set things up to install in the default location <CODE>/usr/local/oz</CODE>. You can change this default using option <CODE>--prefix=$<SPAN class="variablename">PREFIX</SPAN></CODE>. A more complete invocation of configure would look like: </P><BLOCKQUOTE class="code"><CODE>$<SPAN class="variablename">SOURCE</SPAN> --prefix=$<SPAN class="variablename">PREFIX</SPAN> --with-stdlib=$<SPAN class="variablename">STDLIB</SPAN></CODE></BLOCKQUOTE><P> and that's the invocation I would recommend. Next, it's a good idea to set up dependencies in case you need to update the sources and then rebuild what needs rebuilding: </P><BLOCKQUOTE class="code"><CODE>make depend</CODE></BLOCKQUOTE><P> Now, you can build the system: </P><BLOCKQUOTE class="code"><CODE>make</CODE></BLOCKQUOTE><P> And optionally install it: </P><BLOCKQUOTE class="code"><CODE>make install</CODE></BLOCKQUOTE><P> or install it in a different installation directory <CODE>$<SPAN class="variablename">DIR</SPAN></CODE>: </P><BLOCKQUOTE class="code"><CODE>make install <SPAN class="variablename">PREFIX</SPAN>=$<SPAN class="variablename">DIR</SPAN></CODE></BLOCKQUOTE><P> Note that it is not possible to skip the <CODE>make</CODE> step and directly invoke <CODE>make install</CODE>. At the top level <CODE>make</CODE> is equivalent to <CODE>make bootstrap</CODE>. If you want to do it in one command, then you need to type: </P><BLOCKQUOTE class="code"><CODE>make bootstrap install</CODE></BLOCKQUOTE><P> If you need to reconfigure, beware that <CODE>configure</CODE> builds a cache of configuration data in <CODE>$<SPAN class="variablename">BUILD</SPAN>/config.cache</CODE>. You may need to remove that.</P><P>In order to also build the documentation, you need to invoke configure with option: </P><BLOCKQUOTE class="code"><CODE>--with-documents=all</CODE></BLOCKQUOTE><P></P></DIV><DIV id="chap.tarballs"><H1><A name="chap.tarballs">2 Tarballs</A></H1><H2><A name="label1">2.1 Source Tarball</A></H2><P>This assumes that you have checked out the sources and configured a build directory (see <A href="index.html#chap.intro">Chapter 1</A>). The top level <CODE>Makefile</CODE> provides support for creating a source tarball: </P><BLOCKQUOTE class="code"><CODE><SPAN class="builtin">cd</SPAN> $<SPAN class="variablename">BUILD</SPAN> <BR>make src</CODE></BLOCKQUOTE><P> This will result in the creation of file <CODE>mozart-$<SPAN class="variablename">VERSION</SPAN>.$<SPAN class="variablename">DATE</SPAN>-src.tar.gz</CODE> where <CODE>$<SPAN class="variablename">VERSION</SPAN></CODE> is the release number and <CODE>$<SPAN class="variablename">DATE</SPAN></CODE> is the build date (the current date, or rather, the date when you invoked <CODE>configure</CODE>). That's it, you're done.</P><H2><A name="label2">2.2 Documentation Tarball</A></H2><P>For this, you need to build and install the documentation. As mentioned earlier, this requires that you configured using option <CODE>--with-documents=all</CODE>. Note that building the documentation takes very long and you need additional software on your machine (such as LaTeX, nsgmls, Ghostscript, the netpbm package, also java if you are going to build the postscript and pdf documentation, and probably other things I forget).</P><P>Let's assume that you configured, built and installed the system (I will not explain here how to additionally create the Postscript and PDF documentation). The top level <CODE>Makefile</CODE> contains support for creating a documentation tarball: </P><BLOCKQUOTE class="code"><CODE><SPAN class="builtin">cd</SPAN> $<SPAN class="variablename">BUILD</SPAN> <BR>make doc</CODE></BLOCKQUOTE><P> This will suck in all the installed documentation and create file <CODE>mozart-$<SPAN class="variablename">VERSION</SPAN>.$<SPAN class="variablename">DATE</SPAN>-doc.tar.gz</CODE>. If you have installed the standard library, this tarball will also contain its documentation.</P><H2><A name="label3">2.3 Standard Library Tarball</A></H2><P>If you have configured using <CODE>--with-stdlib=$<SPAN class="variablename">STDLIB</SPAN></CODE>, then you can create the standard library tarball with: </P><BLOCKQUOTE class="code"><CODE>make std</CODE></BLOCKQUOTE><P> This will only work after <CODE>make install</CODE> because it uses the installed <CODE>ozengine</CODE> and core libraries. As result the following tarball is created: </P><UL><LI><P><CODE>mozart-$<SPAN class="variablename">VERSION</SPAN>.$<SPAN class="variablename">DATE</SPAN>-$<SPAN class="variablename">PLATFORM</SPAN>-std.tar.gz</CODE></P></LI></UL><P> </P><H2><A name="label4">2.4 Binary Tarballs</A></H2><P>Here again, we assume that you have configured, built and installed the system. The top level <CODE>Makefile</CODE> contains support for creating binary tarballs: </P><BLOCKQUOTE class="code"><CODE><SPAN class="builtin">cd</SPAN> $<SPAN class="variablename">BUILD</SPAN> <BR>make bin</CODE></BLOCKQUOTE><P> This will suck in from the installation directory all necessary files to include in the binary tarballs. As a result, three tarballs are created: </P><UL><LI><P><CODE>mozart-$<SPAN class="variablename">VERSION</SPAN>.$<SPAN class="variablename">DATE</SPAN>-$<SPAN class="variablename">PLATFORM</SPAN>.tar.gz</CODE></P></LI><LI><P><CODE>mozart-$<SPAN class="variablename">VERSION</SPAN>.$<SPAN class="variablename">DATE</SPAN>-$<SPAN class="variablename">PLATFORM</SPAN>-contrib.tar.gz</CODE></P></LI><LI><P><CODE>mozart-$<SPAN class="variablename">VERSION</SPAN>.$<SPAN class="variablename">DATE</SPAN>-$<SPAN class="variablename">PLATFORM</SPAN>-internal.tar.gz</CODE></P></LI></UL><P> where <CODE>$<SPAN class="variablename">PLATFORM</SPAN></CODE> stands for your platform, i. e. the value returned by shell script: </P><BLOCKQUOTE class="code"><CODE>$<SPAN class="variablename">SOURCE</SPAN>/share/bin/ozplatform</CODE></BLOCKQUOTE><P> You can ignore the last tarball. If you have installed the standard library, it will be included in the first tarball.</P><H3><A name="label5">2.4.1 Non-Linux Platforms</A></H3><P>Mozart requires a number of libraries which are not necessarily available by default on Non-Linux platforms. You will need to provide these libraries with the binary release. There are 2 ways: using static linking or using shared object libraries. I will describe the second way. Note, that the situation may be further complicated by the question of whether your platform supports dynamic linking or not. </P><H4><A name="label6">Using Shared Object Libraries</A></H4><P>The aim here is to provide both the compiled system together with the dynamic libraries that it requires. Here is a little known fact: the scripts that invoke OZ utilities are designed to modify the search path for dynamic libraries so that the linker also looks first in: </P><BLOCKQUOTE class="code"><CODE>$<SPAN class="variablename">HOME</SPAN>/.oz/platform/$<SPAN class="variablename">PLATFORM</SPAN>/lib</CODE></BLOCKQUOTE><P> and then in </P><BLOCKQUOTE class="code"><CODE>$<SPAN class="variablename">PREFIX</SPAN>/platform/$<SPAN class="variablename">PLATFORM</SPAN>/lib</CODE></BLOCKQUOTE><P> where <CODE>$<SPAN class="variablename">PREFIX</SPAN></CODE> stands for the installation directory. Thus, the trick is to plunk the necessary shared libraries into this last directory before building the binary tarballs.</P><P>Of course, the assumption is that you will be able to fetch the missing packages and build or otherwise obtain shared object libraries for them. This is usually the case.</P><H4><A name="label7">Tcl/Tk</A></H4><P>This is frequently a pain in the rear. Check other documentation as well as <CODE>$<SPAN class="variablename">SOURCE</SPAN>/platform/wish/configure.in</CODE>.</P></DIV><H1><A name="label8">3 RPMs</A></H1><H2><A name="label9">3.1 Binary RPMs</A></H2><P>If your platform uses RPMs, then you are in luck. Download the source RPM from our download page, become somebody really important (I mean <CODE>root</CODE>) and execute: </P><BLOCKQUOTE class="code"><CODE>rpmbuild --rebuild mozart-$<SPAN class="variablename">VERSION</SPAN>.$<SPAN class="variablename">DATE</SPAN>-src.rpm</CODE></BLOCKQUOTE><P> for newer versions of <CODE>rpm</CODE>. If you have an old version of <CODE>rpm</CODE> which does not provide <CODE>rpmbuild</CODE>, then just invoke <CODE>rpm</CODE> directly as follows: </P><BLOCKQUOTE class="code"><CODE>rpm --rebuild mozart-$<SPAN class="variablename">VERSION</SPAN>.$<SPAN class="variablename">DATE</SPAN>-src.rpm</CODE></BLOCKQUOTE><P> In either case, this will create the binary RPMs in <CODE>/usr/src/redhat/RPMS/i386</CODE>. </P><H2><A name="label10">3.2 Source RPM</A></H2><P>In order to create the source RPM, you need to have already created or downloaded the source, documentation, and standard library tarballs. Assuming that you have placed them in <CODE>$<SPAN class="variablename">BUILD</SPAN></CODE>, become somebody important and execute: </P><BLOCKQUOTE class="code"><CODE>$<SPAN class="variablename">SOURCE</SPAN>/misc/create-rpm $<SPAN class="variablename">BUILD</SPAN> $<SPAN class="variablename">BUILD</SPAN></CODE></BLOCKQUOTE><P> Note that this will create both a source RPM and binary RPMs. They will be placed in <CODE>$<SPAN class="variablename">BUILD</SPAN></CODE> or whatever directory you supplied as the second argument to <CODE>create-rpm</CODE>: </P><UL><LI><P><CODE>mozart-$<SPAN class="variablename">VERSION</SPAN>.$<SPAN class="variablename">DATE</SPAN>-$<SPAN class="variablename">REVISION</SPAN>.src.rpm</CODE></P></LI><LI><P><CODE>mozart-$<SPAN class="variablename">VERSION</SPAN>.$<SPAN class="variablename">DATE</SPAN>-$<SPAN class="variablename">REVISION</SPAN>.i386.rpm</CODE></P></LI><LI><P><CODE>mozart-contrib-$<SPAN class="variablename">VERSION</SPAN>.$<SPAN class="variablename">DATE</SPAN>-$<SPAN class="variablename">REVISION</SPAN>.i386.rpm</CODE></P></LI><LI><P><CODE>mozart-doc-$<SPAN class="variablename">VERSION</SPAN>.$<SPAN class="variablename">DATE</SPAN>-$<SPAN class="variablename">REVISION</SPAN>.i386.rpm</CODE></P></LI></UL><P> </P><H1><A name="label11">4 Check-List For Release Managers</A></H1><P>This chapter is intended for release managers of the Mozart consortium. Below is the very abbreviated list of steps to follow for creating a new release: </P><UL><LI><P>make sure that the files <CODE>config.sub</CODE> and <CODE>config.guess</CODE> are up-to-date. Check for new versions at <A href="ftp://ftp.gnu.org/gnu/config"><CODE>ftp://ftp.gnu.org/gnu/config</CODE></A> </P></LI><LI><P>bump up the version in file <CODE>OZVERSION</CODE></P></LI><LI><P>update version specific changes in <CODE>doc/changes/main.sgml</CODE></P></LI><LI><P>cut a new tag in the CVS. For example, if you wish to cut a tag for version 1.2.3 on the current release branch. You should check it out, cd to the directory of the checked out version and issue the following command: </P><BLOCKQUOTE class="code"><CODE>cvs tag -r mozart-1-2-3</CODE></BLOCKQUOTE><P></P></LI><LI><P>check out the standard library and also cut the same tag in it. Let's call <CODE>$<SPAN class="variablename">STDLIB</SPAN></CODE> the directory into which you checked it out.</P></LI><LI><P>then you should configure, build and install the release: </P><BLOCKQUOTE class="code"><CODE>$<SPAN class="variablename">SOURCE</SPAN>/configure --with-stdlib=$<SPAN class="variablename">STDLIB</SPAN> --with-documents=all</CODE></BLOCKQUOTE><P> You can also supply <CODE>--prefix=$<SPAN class="variablename">PREFIX</SPAN></CODE> if you want to install elsewhere than the default; this has no ill-effect.</P></LI><LI><P>As stated above, you should then <CODE>make</CODE> followed by <CODE>make install</CODE>. If you did not forget the <CODE>--with-stdlib</CODE> option, this will also build and install the standard library.</P></LI><LI><P>Now invoke <CODE>make src doc bin std</CODE> in order to create all the necessary tar files. <CODE>make bin</CODE> creates a file <CODE>README-$<SPAN class="variablename">VERSION</SPAN>.$<SPAN class="variablename">DATE</SPAN>-$<SPAN class="variablename">PLATFORM</SPAN></CODE> which describes the important points about linking: i.e. what libraries <CODE>emulator.exe</CODE> and <CODE>tk.exe</CODE> are dynamically linked against. Note that, depending on whether you used <CODE>--enable-static-linking</CODE> or not, you should rename the tar and README files accordingly so that multiple offerings for the same platform but with different linking policies can be distinguished. My own preference is to add <CODE>-dynfull</CODE> when dynamic linking is used and <CODE>-dynless</CODE> when <CODE>--enable-static-linking</CODE> (and possibly <CODE>--enable-modules-static</CODE> - I normally specify both of them when I am interested in a more statically linked distribution) was used instead. For example, here are the names of the tar and README files for release 1.2.3 for the dynamically linked version of the mozart release for freebsd on the intel architecture: </P><UL><LI><P><CODE>README-1.2.3.20011121-freebsdelf-i486-dynfull</CODE></P></LI><LI><P><CODE>mozart-1.2.3.20011121-freebsdelf-i486-dynfull-contrib.tar.gz</CODE></P></LI><LI><P><CODE>mozart-1.2.3.20011121-freebsdelf-i486-dynfull.tar.gz</CODE></P></LI></UL><P> </P></LI><LI><P>now become root and invoke <CODE>$<SPAN class="variablename">SOURCE</SPAN>/misc/create-rpm $<SPAN class="variablename">PWD</SPAN> $<SPAN class="variablename">PWD</SPAN></CODE>. This creates the source and binary rpms.</P></LI><LI><P>Now you need to create and populate the ftp directory for the release. For this, you need to be logged into the consortium's ftp machine. Currently this is <CODE>grizzly</CODE> in Saarbrücken. Become <CODE>root</CODE>: </P><DL><DT><CODE>perl $<SPAN class="variablename">SOURCE</SPAN>/misc/mkftp --release=$<SPAN class="variablename">VERSION</SPAN> --create</CODE></DT><DD><P>this creates the directory structure for the release. Use option <CODE>-n</CODE> to see what <CODE>mkftp</CODE> would do without actually doing it.</P></DD><DT><CODE>perl $<SPAN class="variablename">SOURCE</SPAN>/misc/mkftp --release=$<SPAN class="variablename">VERSION</SPAN> --tar *.tar.gz README-*</CODE></DT><DD><P>this will install the tar and README files appropriately.</P></DD><DT><CODE>perl $<SPAN class="variablename">SOURCE</SPAN>/misc/mkftp --release=$<SPAN class="variablename">VERSION</SPAN> --rpm=redhat *.rpm</CODE></DT><DD><P>install the source and binary RPMs.</P></DD></DL><P> </P></LI><LI><P>Now you need to make the postscript and pdf documentation. cd to the build doc directory and invoke <CODE>make ps</CODE> followed by <CODE>make pdf</CODE>. Finally do <CODE>make installps</CODE> which installs the documentation in the global <CODE>print</CODE> directory of your installation. Now propagate this documentation to the ftp directory: </P><BLOCKQUOTE class="code"><CODE>perl $<SPAN class="variablename">SOURCE</SPAN>/misc/mkftp --release=$<SPAN class="variablename">VERSION</SPAN> --doc=$<SPAN class="variablename">PREFIX</SPAN></CODE></BLOCKQUOTE><P> </P></LI></UL><P> </P><HR><ADDRESS><A href="http://www.ps.uni-sb.de/~duchier/">Denys Duchier</A><BR><SPAN class="version">Version 1.4.0 (20110908185330)</SPAN></ADDRESS></BODY></HTML>
|