First of all, you should choose a good, short name that aptly
describes your software project. This will be the name of your
official releases, and the name of the CVS module for the release
directory. All your other packages will be nested inside it. From
now on, we will use offline as an example.
To initiate the creation of a production release, you will
invoke the new tool with the -p option and a
CVS tag. This means that there must be package of the given name and
tag in the CVS. To create a offline release 0.0.0, you
would:
set up your environment as explained in Chapter 7, ``Getting Started''
make sure there is a CVS module
offline
make sure the package has been tagged as
offline-00-00-00
invoke the new tool.
If you do not yet have the software, you will need to create a
minimal top level package. However, since we will want to freeze this
as the first release as well, we have to add at least one source
package--otherwise the freezing stage will fail. For
instructions on how to create such a package, please consult Chapter 10, ``Creating A New Package''. Assuming this one source package is called
HelloWorld, one would carry out the following steps:
$ mkdir $CVSROOT/offline
$ cd <some working area path>
$ cvs checkout offline
$ cd offline
$ cp $SRT_HOME/package-configure.in configure.in
$ cp $SRT_HOME/package-GNUmakefile.in GNUmakefile.in
$ echo '# empty' > PACKAGE
$ autoconf -l $SRT_HOME
$ cvs add PACKAGE configure configure.in GNUmakefile.in
$ cvs commit -m \
'offline (PACKAGE, configure, configure.in, GNUmakefile.in): new files'
$ cd ..
$ cvs release -d offline
$ cd <some path>/HelloWorld
$ cvs import -m 'offline/HelloWorld: imported' \
offline/HelloWorld PROJECT HelloWorld-00-00-00
$ cd ..
$ cvs co -d HelloWorld.new offline/HelloWorld
$ gdiff -ru HelloWorld HelloWorld.new
# If significant differences, fix them and repeat from
# import again; gdiff is the GNU version of diff
$ rm -fr HelloWorld
$ cvs release -d HelloWorld.new
$ cvs rtag offline-00-00-00 offline |
You now have a offline package and you can check it
out with the new tool. Note that in the import command
PROJECT was used as the vendor tag; you ought to substitute
whatever token best describes your project. It is usually a good idea
to use a different vendor tag for packages that are not developed in
your project, but simply imported into your repository. Also, apply
whatever version numbers are appropriate to your project, both to the
release and the packages. There is no reason to start from zero if
you are not starting from scratch.
Now, let us create the first release directory. In this
example, we shall call it 0.0.0 since we are dealing with
version 00-00-00 of the release. Note that you
should not use the release's version tag as the directory
name: using the tag appears to confuse the developers to think that it
is the tag of their package, especially if the package is
nested directly below the release. This is of course most of the time
untrue since the release tags rarely have any correlation to the
package tags. A little syntactic difference in the name seems to
relieve the issue. Proceeding with the example, this is what you
should do:
$ srt new -p 0.0.0 offline-00-00-00 |
Then, for each target combination you want to support, you would
carry out the following steps:
$ cd $SRT_DIST/0.0.0
$ mkdir -p .srt/$SRT_TARGET
$ cd .srt/$SRT_TARGET
$ ../../../configure
$ make
$ make check
$ make install
$ make installcheck |
 | You should not get any errors at this point. If you
do, this is absolutely not the proper place to start fixing them. You
will have to roll back and do it somewhere else, remove the release,
reassign the tags to the fixed package versions (not revisions!), and
then retry again from the srt new command. If the
release was made with srt prepare tool as explained
below, you should have caught all the errors at that point. You
should never, absolutely never, do any software development such as
CVS updates, commits, or tags, in the official distribution area. The
whole point of this procedure is that somebody else will be able to
repeat your steps and get exactly the same results. |
You now have a directory $SRT_DIST/0.0.0/installed
that contains the products of your release. Building the
check target should have made sure the programs work, but do
not rely solely on that; developers are known to be lazy creatures.
Make sure the programs work as expected by running some tests with
them. If your packages also generate unix manual pages or other
documentation, you will need to make the install-doc and
install-man targets as well; they are not executed as part
of install. Now, finish off with the following commands:
$ find . -type d -exec touch {}/.www_browsable \;
$ srt freeze |
The first command creates files that convince the web server
that the directory structure is browsable. If you want to let
developers to browse your releases like this, you need to consult your
web server's documentation and configuration to see what is required
to make it happen. You may also need to execute a variant of the
command to make ensure all your developers and the web server have the
proper access permissions.
The second command freezes the release. This should not fail,
but if it does, you will have to start all the way from the beginning.
Thus, it is wise to make sure early enough that the freezing will
succeed. One of the few potential stumbling blocks is that the
freeze tool insists on
running the check tool. It
is not a bad idea to run check yourself right after
executing the new tool to make sure you are not going
to waste lots of time.
When the freeze tool completes successfully, you have
your very first official release and you can advertise it to your
developer community. As you may notice, all the files have been
changed to read-only.[1] This is to protect the
release from being modified. You must never change anything in a
release after freezing it, however trivial that change seems. Create
a new release instead.
Notes
