# How to prepare a Ghostscript release

## Table of contents

> - Introduction
> - Servers
>   - Distribution
> - Making distributions
>   - Preparing the source code
>   - Testing
>   - Making the source distribution
>   - Testing on Windows
>   - Building the Windows distribution
>   - Finishing up
>   - Beta distributions
>   - Public releases
> - After releasing
> - Fonts

For other information, see the Ghostscript overview and the instructions on how to build Ghostscript.

## Introduction

This document describes the process that artofcode LLC, the copyright holder of Ghostscript, uses for making new Ghostscript releases. Please note that while the the license allows anyone to prepare and distribute releases in accordance with its terms and conditions, this document is really meant only to document the process used by artofcode LLC. However, the eventual purpose of this document is to describe Ghostscript release procedures in enough detail that someone who knows little about Ghostscript but is generally familiar with the platform on which the procedure is being carried out can execute the procedures correctly. So if you add or changing anything to/in this document, be sure to specify all command lines, file names, etc. in explicit detail.

File names below that don't include an explicit subdirectory name are in the `src` subdirectory.

If you do plan to make your own distribution, please be aware of some items you will want to change.

- If you make any significant changes, please edit `gscdef.c` to change `GS_PRODUCTFAMILY` and `GS_PRODUCT` from "GNU Ghostscript" to something else, in order to avoid confusion with artofcode's releases.
- In the same file, you may also want to edit `GS_COPYRIGHT` to add your own copyright notice (although you must not remove any notice that is there).
- You will almost certainly want to edit `version.mak` to change the revision date, `GS_REVISIONDATE`.
- If you want to change the version number, you must change it in both `version.mak` (`GS_VERSION_`*) and `lib/gs_init.ps` (the integer on a line by itself near the beginning of the file).

## Servers

The Ghostscript source files are maintained on sites accessible to the public. One specific site hosts the active CVS repository for code, data, and documentation, and the bug report data base; several sites offer distributions with version numbers, intended for wider distribution.

### Distribution

The primary distribution site for GNU Ghostscript is the GNU ftp site and its mirrors.

Stable releases are also distributed from

> ftp://mirror.cs.wisc.edu/pub/mirrors/ghost/gnu/

## Making distributions

This document only discusses source distributions. Source distributions currently can only be made on GNU/Linux systems (but it probably wouldn't take much work to support other Unix-like systems). Ghostscript as distributed also often includes executables or other packages for the Windows and MacOS environments, but artofcode does not produce these, and this document does not discuss them. For more information about Windows packages, please contact `bug-gswin@ghostscript.com`; for more information about MacOS packages, please contact `mac-gs@ghostscript.com`.

To make a source distribution, you will need the scripts and data files in the `toolbin/` directory. The instructions below generally assume that you're invoking the relative to the top level of the source tree. To run the scripts, you will need reasonably current versions of Tcl, freely available from Scriptics (`http://www.scriptics.com`), and Python, freely available from `http://www.python.org`.

The instructions below also refer to some files that are deliberately omitted from the public distribution, because they are not freely redistributable. You will need to provide similar files for your environment.

>     data/*/*.ps (PostScript files) - needed for smoke testing

### Preparing the source code

Update references to the date for release:

- In `lib/gs_init.ps`, as an integer (release number x100) at the beginning of the file just after the initial comment blocks.
- In `version.mak`, the numeric date.
- In `doc/News.htm`, in two places, skipping the Id: line. That is, in parentheses after the `VERSION X.YY` heading, and in the copyright footer both the year and the release date.

We recommend using a UTC release date to avoid timezone skew.

Also in `doc/News.htm`, update the number of the highest closed bug and the list of open bugs.

Check in `gscdef.c` that the definition of `GS_PRODUCT` includes the appropriate one of "DEVELOPMENT RELEASE", "BETA RELEASE", or neither, and does not include "CVS PRE-RELEASE".

Run the source-consistency checks from the test suite:

>     toolbin/tests/check_all.py --gsroot=.

Where the argument of --gsroot is the path to the top level of the source tree. Fix any problems it indicates, and commit them to cvs.

Check for patched configuration parameters, `#define TEST`s, version/date inconsistencies, and mismatches between the working directory and the CVS repository by running:

>     toolbin/pre

This program compares the result of various greps against a check file, writing the results of grep on one output file and the differences from the check file on another. See the source code of `toolbin/pre` for the default file names. The important one is the check file, `toolbin/pre.chk`. `pre` also verifies that the right information is in the following places:

- version number in `man/*.1`, `doc/*.htm`, `version.mak`, `doc/gs-vms.hlp`, `lib/gs_init.ps`
- revision date in `man/*.1`, `doc/*.htm`, `version.mak`, `doc/gs-vms.hlp`
- copyright year (if necessary) in `gscdef.c`
- third-party library version number in `*.mak`

If necessary, run

>     toolbin/pre update

to update the version and revision date in the doc files, and then run

>     toolbin/pre

again. To confirm that everything is updated. You may have to commit to cvs after the update to satify the script that all the dates are correct.

Check the consistency of the source code with the makefiles by running:

>     toolbin/gsmake.tcl check

This script assumes the top level makefile is named '`makefile`'.

Fix any problems and commit to cvs.

### Testing

Edit your top-level the Makefile to set

>     FEATURE_DEVS=$(FEATURE_DEVS_ALL)
>     COMPILE_INITS=1

This will help catch compilation problems.

Run

>     rm obj/*
>     make -j2 >& make.log

and look for warnings and errors in the log file.

Do a smoke test, updating the example paths as necessary:

>     unset GS_DEVICE GS_FONTPATH GS_LIB GS_OPTIONS
>     ./bin/gs -I./lib -I./fonts -dNOPAUSE -dBATCH /gs/toolbin/smoke.ps
>     ./bin/gs -I./lib -I./fonts -dNOPAUSE -dBATCH -sDEVICE=bitcmyk\
>       -sOutputFile=/dev/null -r600 -dBufferSpace=50000 /gs/toolbin/smoke.ps

This reads files named

>     data/misc/*.ps
>     data/ps/*.ps
>     data/psl2/*.ps
>     data/psl3/*.ps
>     data/pdf/*.pdf

(Edit `toolbin/smoke.ps` to use other test sets.) Watch for crashes, unusual error messages, or anomalous displayed output. If there are any problems, start over from the beginning of the process.

Undo the `FEATURE_DEVS` and `COMPILE_INITS` edits.

Run

>     cvs commit

to ensure the repository is up to date.

Execute

>     toolbin/cvs2hist.py -j <previous_tag> -r '-r<branch_tag>' -v <new_version> > doc/Changes.htm

> e.g.

>     toolbin/cvs2hist.py -j gs7_04 -r '-rGS_7_0X' -v 7.05

This consolidates all the CVS logs since the previous release in a readable format. Note: the cvs2hist.py tool currently in the distribution is not very branch-aware (nor is the 'cvs log' command it depends on) so the extra complication of the -j and -r options are required when generating the Changes for a non-HEAD branch of Ghostscript. Note that the -r option should be an empty '-b' when generating logs for the cvs main branch due to variations in naming.

Run

>     tclsh
>     % source toolbin/makeset.tcl
>     % makehist

This updates `doc/History#.htm` from `doc/News.htm` and `doc/Changes.htm`. Then run

>     cvs commit

again to check in the Changes and history files.

### Making the source distribution

First, tag the versions of the files in cvs with the release version number.

>     cvs tag gs#_##

If you've already tagged this release (e.g. in making an earlier release candidate) you'll need to add the `-r` and `-F` options after 'cvs tag' to force moving the tag to the new revisions of changed files.

Pull a fresh copy for distribution from the cvs repository:

>     cvs -z3 -d <ghostscript cvsroot> export -r gs#_## -d ghostscript-#.## gs

Generate the text versions of the README document:

>     cd ghostscript-#.##
>     lynx -dump -nolist doc/Readme.htm > doc/README

For the unix source distributions only, generate the configure scripts. From the top level directory, run

>     ./autogen.sh
>     make distclean

This should create links to `configure.ac` and `Makefile.in` in the top level directory and invoke autoconf to create the `configure` script.

Also, run `autoconf` in the ijs subdir to create the configure script for that package.

Move back to directory containing the distribution code and make the source archives with:

>     tar cvzf ghostscript-#.##.tar.gz ghostscript-#.##/*
>     zcat ghostscript-#.##.tar.gz | bzip2 -c > ghostscript-#.##.tar.bz2

This creates the files

>     ghostscript-#.##.tar.gz (main archive)
>     ghostscript-#.##.tar.bz2 (main archive)

The important issue is that the tarballs unpack into a directory of the same name, and that the code be a pristine copy without build or CVS housekeeping files.

It is also customary to make a `gs###src.zip` archive for the convenience of windows developers. See below.

### Testing on Windows

For Windows testing, you will need, in addition to the files listed under "Preparing the source" above:

>     toolbin/makewin (link to makeset.tcl)

The following procedures rely on a large number of MS-DOS batch scripts that are not discussed here: they are unlikely to be generally useful.

Mount the Windows partition on `/c`, and create the `/c/work` directory if needed.

Make the zip archive of all files needed for a Windows build, and copy it to the Windows partition:

>     toolbin/makewin
>     cp gs###.zip /c/work

Boot into Windows. Unpack the archive:

>     cd \work
>     unzip -oq gs###.zip
>     gs###

The `gs###.bat` script creates some necessary directories, sets up `PATH` and `GS_LIB` for testing, and makes the `gs#.##` directory current.

Build with the Borland compiler:

>     config bcwin32
>     copy /y /b ..\gs\makefile
>     erase obj\*.*
>     make > bc.log

Smoke test the executables (both `gswin32` and `gswin32c`), as described above for source distributions. Then build with the Microsoft compiler:

>     config msvc32
>     copy /y /b ..\gs\makefile
>     erase obj\*.*
>     nmake > msvc.log

Smoke test these executables too.

Building with the Watcom compiler doesn't work, because the `wmake` or `wmakel` program runs out of memory. However, if it did work, this is how to do it:

>     config watcw32
>     copy /y /b ..\gs\makefile
>     erase obj\*.*
>     wmake -u > watc.log

Boot back into GNU/Linux. If testing in Windows revealed problems, edit the source files as necessary, and go back to "Preparing the source code."

### Building the Windows distribution

Extract the sources from `ghostscript-N.NN.tar.gz` then repackage in a zip file as follows:

> `zip -r temp.zip gsN.NN/doc gsN.NN/examples gsN.NN/icclib gsN.NN/ijs gsN.NN/lib gsN.NN/src`

Unzip converting the line endings to CRLF:

> `unzip -a temp.zip
> del temp.zip`

Then finally zip up the sources to the distribution file:

> `zip -9 -r gsNNNsrc.zip gsN.NN`

This method is reasonably portable, and does not convert binary files such as `examples/annots.pdf`.

Unzip `gsNNNsrc.zip`. The directory must be named `gsN.NN`.

Extract the fonts `gnu-gs-fonts-std-6.0.tar.gz` into a directory `fonts` adjacent to the `gsN.NN` directory. The fonts are needed in this location for building the distribution archive later.

You will need the command line Info-Zip zip program available from http://www.info-zip.org/pub/infozip/ Alternatively, the command line version of WinZip (`wzzip.exe`) can be used by replacing the Info-Zip command line options `-9 -r` with `-ex -P` in `winint.mak`.

You will need WinZip Self-Extractor for building the self extracting archive. This is commercial software. You may need to update the path `WINZIPSE_XE` in `winint.mak`.

Unzip the jpeg, libpng and zlib libraries, then make ghostscript as documented in Make.htm.

Run the command `nmake archive`. This builds the distribution archive `gsNNNw32.exe` and an ordinary zip file `gsNNNw32.zip` in the parent directory. If you do not have WinZip Self-Extractor, you can use `nmake zip` to make `gsNNNw32.zip` only.

### Finishing up

Upload `ghostscript-#.##.tar.*` to SourceForge (by anonymous FTP to `upload.sourceforge.net`, directory `/incoming`), and then post it using the "File Release" facility in the Ghostscript project. If this is a GNU release, put it in the `gnu-gs` module. If this is a test release or beta release, put it in the `gs-devel` or `gs-beta` module, respectively. If you are adding executable builds or source archives for other platforms to an existing source release, please use the same release date as the source release, not the current date.

### Beta distributions

Do the steps for distributions in general.

Upload `ghostscript-#.##.tar.*` to the testing directory on mirror.cs.wisc.edu.

Send an email announcement to the `gs-test` list announcing the new release.

### Public releases

Update the title (current version #), first heading (previous version #), and "new features" and "known problems" lists in `doc/Current.htm`.

Do the steps for distributions in general.

Create a directory at `ftp://mirror.cs.wisc.edu/pub/mirrors/ghost/gnu/gs###/`. In that directory, store the following files:

- Standard distribution files:

  >     ghostscript-#.##.tar.gz
  >     ghostscript-#.##.tar.bz2

- MS Windows source and executables:

  >     gs###src.zip
  >     gs###w32.exe
  >     gs###w32.zip

- Third-party libraries, as links (upload these if not installed), where `$$$` et al. refer to the version number of the library, which should be the latest compatible release of the library and should be consistent with the values of and version numbers specifically listed in the makefiles.

  >     jpegsrc.v$$.tar.gz -> ../../3rdparty/jpegsrc.v$$.tar.gz
  >     libpng-$.$.$.tar.gz -> ../../3rdparty/libpng-$.$.$.tar.gz
  >     zlib-$.$.$.tar.gz -> ../../3rdparty/zlib-$.$.$.tar.gz
  >     jpegsr$$.zip -> ../../3rdparty/jpegsr$$.zip
  >     lpng$$$.zip -> ../../3rdparty/lpng$$$.zip
  >     zlib$$$.zip -> ../../3rdparty/zlib$$$.zip

  In any case, the names of the links in the distribution directory should reflect the original name of the upstream file.
- Fonts, where `$.$$` refers to the most recent version number of the fonts:

  >     ghostscript-fonts-other-$.$.tar.gz -> ../fonts/ghostscript-fonts-other-$.$.tar.gz
  >     ghostscript-fonts-std-$.$.tar.gz -> ../fonts/ghostscript-fonts-std-$.$.tar.gz

(Note that the link names are somewhat inconsistent: some of them retain the version number of the file being referenced, and some of them use the Ghostscript version number. This is a historical artifact that might be changed someday.)

E-mail the release announcement using:

>     To: gs-announce

Edit the Web pages in cvs and commit to reflect the new release. The Wisconsin server should update automatically.

## After releasing

E-mail the full URL and the `md5sum` of the new archive(s) to `ftp-upload@gnu.org`. This will allow the site maintainers to add the new release to the GNU distribution network.

It may also be helpful to have the Free Software Foundation review the code before release to see whether it meets their standards for distribution from the gnu.org website.

Update the version number by incrementing it:

- In `lib/gs_init.ps`, at the very beginning of the file.
- In `version.mak`, in 3 definitions.
- In `doc/News.htm`, in 4 places.

In `gscdef.c`, edit the definition of `GS_PRODUCT` to include "CVS PRE-RELEASE".

Edit `doc/News.htm` to remove all the content.

## Fonts

artofcode LLC distributes a package of the base 35 PostScript fonts, and a package of other miscellaneous fonts. These are released with a licence matching that of the Ghostscript code.

To make the font packages, run the command

>     toolbin/makefonts #.##

This creates the following files:

>     ghostscript-fonts-std-#.##.tar.gz
>     ghostscript-fonts-other-#.##.tar.gz
>     gnu-gs-fonts-std-#.##.tar.gz
>     gnu-gs-fonts-other-#.##.tar.gz

The second two should be uploaded to `ftp://mirror.cs.wisc.edu/pub/mirrors/ghost/gnu/fonts/`, and the url and md5sum sent to the GNU ftp maintainers as with the ghostscript source.

Copyright © 1999-2002 artofcode LLC. All rights reserved.

This software is provided AS-IS with no warranty, either express or implied. This software is distributed under license and may not be copied, modified or distributed except as expressly authorized under the terms of the license contained in the file LICENSE in this distribution.

Ghostscript version 7.07, 17 May 2003