# Building the Download Packages

How to create the download packages for a new release and publish them
as unversioned files (uv) in the Fossil repository.

Starting point: the new version has been checked in and tagged
(e.g. `version-1.11`). The version number itself is maintained in one
place only: `AC_INIT([ooxml],[x.y])` in `configure.ac`.

## Prerequisites

* A Fossil checkout of the release check-in:

      fossil update version-1.11

* The Fossil setting `manifest` must be enabled, so that the files
  `manifest` and `manifest.uuid` exist in the checkout and are kept
  up to date on every update:

      fossil settings manifest on

* A configured build directory (`./configure` has been run at least
  once), `tclsh`, `autoconf`, `zip` and `tar` in the PATH.

## 1. Build the packages

    make release

That is all. The target resolves its prerequisites automatically:

* `configure`, `Makefile` and `pkgIndex.tcl` are regenerated if
  `configure.ac` or their templates changed (so a version bump in
  `configure.ac` propagates without a manual `./configure` run),
* `manifest.txt` — the version and build information (check-in UUID,
  check-in date, release version) — is regenerated from `manifest`,
  `manifest.uuid` and `configure.ac` by `tools/mkversion.tcl`,
* `tools/archive.sh` then creates the artifacts in `uv/`:

| File                    | Content                                              |
|-------------------------|------------------------------------------------------|
| `ooxml<x.y>.zip`        | Installable package: Tcl sources, `pkgIndex.tcl`, `manifest.txt` |
| `ooxml<x.y>.tar.gz`     | Same content as the zip                              |
| `ooxml<x.y>-src.tar.gz` | Complete source tree (without build artifacts)       |
| `download.html`         | Download page, generated from `template-download.html` |

The archives are created without macOS metadata (AppleDouble files,
extended attributes, `.DS_Store`).

Check the result before publishing, e.g.:

    unzip -l uv/ooxml<x.y>.zip
    tar tzf uv/ooxml<x.y>.tar.gz

## 2. Publish as Fossil unversioned files

    make publish

This uploads the four artifacts into the uv space of the repository
(`fossil uv add ...`), syncs them to the server (`fossil uv sync`) and
shows the resulting file list (`fossil uv list`).

The packages are then available for download at
<https://fossil.sowaswie.de/ooxml>.

## Notes

* `make archive` still exists as the bare packaging step; `make
  release` is `archive` plus the dependency chain and a summary.
* `tools/archive.sh` is not meant to be called directly; it expects
  `PACKAGE_NAME PACKAGE_VERSION PKG_TCL_SOURCES...` as arguments and
  exits with a usage message otherwise.

## Troubleshooting

* **`can't open file manifest.uuid`** (from `mkversion.tcl`) — the
  Fossil `manifest` setting is off; enable it as described under
  Prerequisites.
* **`make: *** No rule to make target 'release'`** — the `Makefile`
  in the build directory predates this target; run `./configure`
  once to regenerate it.
* **Wrong version in the archive names** — the checkout is not on the
  release check-in (`fossil status`), or `configure.ac` does not
  carry the new version yet.
