How to prepare an Aladdin Ghostscript release

## Table of contents

> - Introduction
> - Servers
>   - Development sources and bug reports
>   - Distributions
> - Adding or removing files
> - Making distributions
>   - Preparing the source code
>   - Testing
>     - Testing on Windows
>   - Finishing up
>     - Tester or beta distributions
>     - Public releases
>     - After releasing

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

# Introduction

This document is a rough set of internal notes that Aladdin Enterprises uses to manage the process of making new Ghostscript releases. As time goes on, it will become a more suitable document for others wishing to prepare releases for distribution. Although the Aladdin Free Public License allows anyone to prepare and distribute releases, this document is really meant only for developers working closely with Aladdin.

This document refers to many script files that are not currently part of the Ghostscript distribution. In the course of time, these scripts will become part of the distribution, probably in a new subdirectory.

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 "Aladdin Ghostscript" to something else, in order to avoid confusion with Aladdin'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 Aladdin's notice).
- 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 Aladdin Ghostscript 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.

## Development sources and bug reports

The development site for Aladdin Ghostscript is SourceForge (`http://sourceforge.net`). Please read the SourceForge Aladdin Ghostscript home page (`http://ghostscript.sourceforge.net`) first. CVS access information is available at `http://sourceforge.net/cvs/?group_id=1897`.

## Distributions

Both public and tester releases are available from

>     http://sourceforge.net/project/filelist.php?group_id=1897

Public (tested) releases are distributed from

>     ftp://ftp.cs.wisc.edu/ghost/aladdin/

Tester releases are distributed from

>     ftp://ftp.cs.wisc.edu/ghost/aladdin/test/
>     ftp://www.aladdin.com/ghost/aladdin/test/

# Adding or removing files

When adding or removing files, don't forget to invoke `cvs add` or `cvs rm`.

When adding or removing files other than .c or .h: If the files are included in the fileset (i.e., not just support files), check the install list in `unixinst.mak`.

When adding .c files, update the relevant `.mak` file (usually `devs.mak`, `int.mak`, or `lib.mak`).

When adding operators, update `doc/Language.htm` if desired.

When adding .h files, add a _h definition in the appropriate `.mak` file.

When adding or changing fonts, update `Fontmap.GS`, `fonts.mak`, and possibly the compiled fonts in `gs.mak` and the examples in `doc/Fonts.htm`.

When adding or changing filters, update `doc/Language.htm`.

When adding .ps files, update `doc/Psfiles.htm`.

# Making distributions

This document only discusses source distributions. Source distributions currently can only be made on Linux systems (but it probably wouldn't take much work to support other Unix systems). Ghostscript as distributed also often includes Windows executables or other packages for the Windows environment, but Aladdin does not produce these, and this document does not discuss them. For more information about this topic, please contact `bug-gswin@aladdin.com` or `gsview@ghostgum.com.au`.

To make a source distribution, you will need the following tools:

>     cvs2hist.py (Python script -- anywhere in the path)
>     cvs2hist (link to cvs2hist.py, ibid.)
>     ../bin/precheck.tcl (Tcl script)
>     master/pre (Tcl script)
>     master/pre.chk (data file)
>     master/gsmake.tcl (Tcl script)
>     master/gsmake (link to gsmake.tcl)
>     master/makeset.tcl (Tcl script)
>     master/makehist (link to makeset.tcl)
>     master/makefonts (ibid.)
>     master/maketars (ibid.)
>     master/makemaster (ibid.)
>     master/smoke.ps (PostScript file)
>     data/*/*.ps (PostScript files)
>     beta.msg

Make sure the release date and version number are up to date in `version.mak`, `lib/gs_init.ps`, and `doc/News.htm`.

## Preparing the source code

Check in `gscdef.c` that the definition of `GS_PRODUCT` includes the appropriate one of "TESTER RELEASE", "BETA RELEASE", or neither.

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

>     master/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 `master/pre` for the default file names. The important one is the check file, `master/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`

If necessary, run

>     master/pre update

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

>     master/pre

again.

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

>     master/gsmake check

Edit the makefile (presumably `unix-gcc.mak`) to set

>     FEATURE_DEVS=$(FEATURE_DEVS_ALL)
>     COMPILE_INITS=1

This will help catch compilation problems.

Run

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

and look for warnings and errors in the log file.

Do a smoke test:

>     bin/gs @b master/smoke.ps
>     export TEMP=/gs/tmp
>     bin/gs @b -sDEVICE=bitcmyk -sOutputFile=/dev/null -r600 -dMaxBitmap=1000000\
>       master/smoke.ps

Undo the `FEATURE_DEVS` and `COMPILE_INITS` edits.

Run

>     cvs commit

to ensure the repository is up to date.

Execute

>     cvs2hist -v #.#[#] > doc/Changes.htm

This consolidates all the CVS logs since the previous release in a readable format.

Run

>     master/makehist

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

>     cvs commit

again.

Make the source archives with

>     master/maketars

This creates the files

>     ghostscript-#.##.tar.gz (main archive)
>     ghostscript-#.##.tar.bz2 (main archive)
>     ghostscript-#.##gnu.tar.gz (GPL'ed files)

## Testing

Unpack the main archive in a clean directory. Prepare for building:

>     ln -s src/unix-gcc.mak makefile;\
>     ln -s /gs/jpeg jpeg; ln -s /gs/libpng libpng; ln -s /gs/zlib zlib

Do a full build and smoke test (in a separate window):

>     unset GS_LIB
>     bin/gs -Ilib -I/gs/fonts -dNOPAUSE -dBATCH /gs/master/smoke.ps | tee t
>     export TEMP=/gs/tmp
>     bin/gs -Ilib -I/gs/fonts -dNOPAUSE -dBATCH -sDEVICE=bitcmyk\
>       -sOutputFile=/dev/null -r600 -dMaxBitmap=1000000 /gs/master/smoke.ps | tee t

This reads files named

>     /gs/data/ps/*.ps
>     /gs/data/psl2/*.ps
>     /gs/data/psl3/*.ps
>     /gs/data/test/*.ps

(Edit `smoke.ps` ad lib 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.

## Testing on Windows

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

>     master/makewin (link to makeset.tcl)

The following procedures are very Aladdin-specific; they rely on a large number of MS-DOS batch scripts that are not discussed here.

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:

>     master/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 Linux. If testing in Windows revealed problems, edit the source files as necessary, and go back to "Preparing the source code."

## Finishing up

If you are maintaining local master copies, execute

>     master/makemaster

This creates `master/###` if necessary, and moves the archives to it.

Tag the source files with the release number by executing

>     cvs tag gs#_#[#]

Upload and post `ghostscript-#.##.tar.*` to SourceForge using the "File Release" facility in the Aladdin Ghostscript project.

If `ansi2knr.c` has changed, put it on `ftp://ftp.cs.wisc.edu/ghost/ansi2knr.c`.

If `doc/C-style.htm` has changed, put it on `ftp://ftp.cs.wisc.edu/ghost/aladdin/C-style.htm`.

### Tester or beta distributions

Do the steps for distributions in general.

Upload `ghostscript-#.##.tar.*` to `ftp://ftp.cs.wisc.edu/ghost/aladdin/test`.

Copy the same files from there to `ftp://www.aladdin.com/pub/ftp/ghost/aladdin/test`.

Construct the e-mail announcement by editing `beta.msg`; include the News section for this release. Mail using:

>     To: gs-test

### 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.

E-mail the release announcement using:

>     To: gs-announce

Edit the Web pages on the Wisconsin server to reflect the new release.

### After releasing

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

Copyright © 1999, 2000 Aladdin Enterprises. All rights reserved.

This file is part of Aladdin Ghostscript. See the Aladdin Free Public License (the "License") for full details of the terms of using, copying, modifying, and redistributing Aladdin Ghostscript.

Ghostscript version 6.01, 16 March 2000