Notes on making FB releases

In general
Packaging and Manifests
Toolchain/build environment
Release making script
FB manual/documentation
Summary: currently the easiest way to build a release

In general

Making an FB release means:
The new release should be compilable with the previous version, so others can bootstrap it if wanted. Ideally it is compilable with even older versions.

FB releases in form of prebuilt binaries should be made at least for DOS, Linux, and Win32. The DOS and Win32 packages traditionally are standalone builds coming with prebuilt binutils and MinGW/DJGPP libraries. The Linux package traditionally is a normal build intended to be installed into /usr or /usr/local and uses the system's binutils/libraries.

All the binary packages must effectively be built from the same source revision. All the to-be-released fbc binaries should be built with the same date, preferably on the same day the release is published. It's confusing to have multiple fbcs each with the same version number but different dates; are they the same version or not?

The sources must be packaged and uploaded in parallel to the binary packages. That includes sources for third-party binaries included in the FB binary packages, e.g. binutils, gdb, gcc, DJGPP/MinGW libs, etc.

To test the releases, it can be useful to
Linux packages must be .tar.gz, Windows/DOS packages must be .zip. Other formats such as .tar.xz or .7z should be offered additionally, but note that there are people with e.g. older GNU/Linux systems that don't know .tar.lzma or .tar.xz, or with Windows systems that don't have 7-zip installed.

Packaging and Manifests

The FB makefile offers the gitdist command for packaging the source code via git archive, and the bindist command for packaging previously built binaries. Example workflow:
# Go to fbc Git clone
cd fbc

# Compile FB

# Package the source code
make gitdist

# Package the binaries, regenerate the manifest
make bindist

# Check the manifest
git diff

gitdist creates source tarballs in multiple formats. It assumes that all changes to the fbc source code used for building the release have been committed to Git.

bindist creates the needed binary archive(s), potentially in multiple formats, with the proper package name and directory layout depending on the target platform and whether it's a normal or standalone build, and it (re)generates the corresponding manifest (list of all files included in the archive) in the contrib/manifest/ directory in the fbc source tree.

By checking the manifest differences via Git (git diff, git gui, etc.) you can check whether any files are missing in comparison to the previous release, or whether files were added that should not be included. Should there be any such issues, they may need to be fixed manually (possible the makefile's bindist implementation needs updating, or you simply need to copy in missing files), after which make bindist can be run again to recreate the package and update the manifest again.

bindist configuration options:

  • Linux/BSD normal, Windows/DOS standalone: FreeBASIC-x.xx.x-target
  • Linux/BSD standalone: FreeBASIC-x.xx.x-target-standalone
  • Windows/DOS normal (MinGW/DJGPP-style packages): fbc-x.xx.x-target

Toolchain/build environment

When making an FB release, the GCC toolchain used to build FB has a huge impact, because FB itself will basically become a modified/extended version of that toolchain. The FB-dos and FB-win32 releases include libraries from the used DJGPP/MinGW toolchains, and they will be used for any FB programs made with those FB builds. Even the FB-linux release will depend on the gcc/glibc version it was built with, because of the precompiled rtlib/gfxlib2 libraries, and because of fbc which will have been linked against shared libraries that may not exist on other systems.

Additionally, different GCC toolchains and runtime libraries (e.g. vs. MinGW-w64, or DJGPP 2.03 vs. 2.04 vs. CVS) can be more or less different in terms of ABI compatibility or runtime behaviour. As such any FB program can behave differently depending on the GCC toolchain, including fbc itself.

More information:
Release making script

The FB sources contain a release-making script at contrib/release/

This script downloads & extracts DJGPP/ toolchains, FB packages for bootstrapping, fbc sources, etc., then builds normal and standalone versions of fbc, and finally creates the complete packages ready to be released.
cd contrib/release
./ <target> <fbc-commit>

<target> can be one of:
Some of the ideas behind this script:
FB manual/documentation

Summary: currently the easiest way to build a release

Back to FreeBASIC Developer Information

Back to Table of Contents
Valid XHTML :: Valid CSS: :: Powered by WikkaWiki phatcode