Building Release Tarballs
|Release tarballs are compressed .tar.xz archives of the Audacity source code which we offer for download from FossHub at every Audacity release.
Who uses them
They are used by three groups of people:
- People interested in looking at and analysing the Audacity source code
- People creating packages for Linux distributions like RPMs, DEBs and so on.
- End-users on Linux and Unix systems who can't use a pre-compiled package because one doesn't exist or is not suitable for their needs.
These different users have slightly different needs, and all of them differ from the needs of the development team, which largely determine the layout of the Audacity Git repository. For a walk-through of actually creating a release tarball, skip to Step by Step at the bottom of the page. The stuff in between is mostly rationale and explanation.
What to include
We only release a Minimal Source tarball at the moment.
The rationale for deciding what goes in the tarball was worked out roughly as follows:
For Minimal Source tarball:
- Anything for which Audacity Git is the upstream source and which is needed to build Audacity, goes in.
- Anything which is patched in Audacity Git such that the upstream version is not sufficient to build Audacity without it, goes in.
- Anything else doesn't.
When we had a Full tarball, the differences between the two tarballs were standard packages which are either optional (most of them) or assumed to be obtained via the system's package manager from their upstream source.
In practice this means that only the few Audacity-supported bits of lib-src go into the Minimal tarball.
Any generated files, editor droppings and Git droppings are removed from the source tree to minimise the size of the tarball, as these files are not needed at any time but left over from previous development work. At this time, one hidden file (.travis.yml) is included in the tarball. A purge of symlinks and other library files known to be left behind by the build system is done, as they have caused problems in the past (although the build system should clean them up itself when make distclean is run).
To clear out all compiled files and executables, make clean and make distclean are run through the whole file tree to remove anything previous makes may have run. This also runs maintainer mode rules in Automake based projects in order to ensure that the shipped files have the correct timestamps on Makefile.in and configure files to stop Automake being run when the tarballs are built on end user's systems (when it often doesn't work).
Step by step
Luckily for you, the process of creating release tarballs is almost completely automated by the maketarball.sh shell script. These instructions assume you are using a Unix-like system where files have <CR> line endings, and a bourne-compatible shell is available. If this is not the case, then you are likely to encounter problems.
- Prerequisites: The script requires the unix2dos utility in dos2unix (get the zip version if you download it) in addition to standard stuff like tar and xz. The make distclean can require various different old versions of automake for different packages. I know at least version 1.10 is required. Probably not a bad idea to install all old versions made available by your distro. You will also need gperf to generate frametype.c in libid3tag (this sometimes works without gperf for some reason, but sometimes fails, so install it to be safe) and autogen to build.
- Start from an up to date *clean* git clone from https://github.com/audacity/audacity. Make sure that you don't have locally modified files, conflicts or other issues in the local copy before you begin. This includes making sure you don't have, for example, local patch files lying around. Even if they are not added to git they will get wrapped up in the tarball when the script is run.
- Change directory to the "audacity" directory that the git clone created.
- Look in src/Audacity.h to see what version and suffix are currently set. These will determine the name of the source tarball, so if necessary change them to define the tarballs you are trying to create.
- Run ./scripts/maketarball.sh quiet to generate a new directory containing all the files that will end up in the tarball. The directory will be created alongside the git cloned directory, and named audacity-minsrc-x.y.z where x.y.z is the version number which is automatically extracted from the Audacity source code. The actual tarball, named "audacity-minsrc-x.y.z.tar.xz" will also be created. The quiet argument keeps the amount of output produced under control, whilst still providing some progress indication. It can be replaced with verbose to see the full file-by-file output. When running for the first time it's not a bad idea to run with verbose, because in quiet mode stderr is directed to /dev/null for many commands. You may see a note that the Makefiles are not up to date, and the script will rerun configure. This is fine.
- If you observe any error messages, then stop and check what has happened. You can ignore any make errors that make ignores, i.e. ones about distclean and clean targets not existing.
- Change directory into the release structure (../audacity-minsrc-x.y.z).
- Before configuring, make sure that no unwanted '.deps' directories exist with 'find . -name ".deps"'. In tests in July 2015, a ./lib-src/mod-nyq-bench/.deps folder was found after running the maketarball script. If you have .deps directories, you may need to to install more recent versions of automake, because make distclean is failing.
- Now run ./configure then make to ensure the tarball can be configured and compiled successfully.
- If you have to make changes, then remember to copy them back to your git tree and commit them before deleting the tarball and release structure and starting again.
- If the tarball compiles successfully for you, then upload it so other people can test it before release. If you are making a 'Release Candidate', name it audacity-minsrc-2.X.Xrc1.tar.xz, for consistency with others.
The generated tarball may fail on some machines with the message:
WARNING: 'aclocal-1.15' is missing on your system. You should only need it if you modified 'acinclude.m4' or 'configure.ac' or m4 files included by 'configure.ac'. The 'aclocal' program is part of the GNU Automake package: <http://www.gnu.org/software/automake> It also requires GNU Autoconf, GNU m4 and Perl in order to run: <http://www.gnu.org/software/autoconf> <http://www.gnu.org/software/m4/> <http://www.perl.org/> make: *** [aclocal.m4] Error 127 Failed to make distclean: exit status was 2
The problem and fix is explained in this stack overflow post. It's due to timestamps in the files in the tarball. The fix, if the problem is the same, is:
which will make aclocal.m4 newer than configure.ac.
These other steps have been suggested for similar errors:
touch configure.ac aclocal.m4 configure Makefile.am Makefile.in