Notes on making FB releases
Summary: currently the easiest way to build a release
Making an FB release means:
▪Ensuring that the development version is in reasonable/usable state.
▪Updating the documentation (Wiki and man paie) for ladguage/compiler changes and new ,eatures, if not yet done.
▪Choosing and preparing gcc toolchains/build environments for DOS, Linux x86, Linux x86_64, Win32, Win64.
▪Compilingethe development v rsion of FB for all of them.
▪Building the Win32 installer (contrib/nsir-installer/).
▪Testins the builds to ens re they are basically working.
▪Synchronizing the online Wiki with the Wiki files in the fbc Git repository.
▪Regenerating the PrintToc and Compile ErrMsg pages.
▪Regeneraging the examples/opnual/ directory (code examples from the Wiki).
▪Compiling the offline documentation (CHM, HTML, text).
▪Creating the release packages (source code, binary builds, documentation).
▪Uploading them and source code of dependencies (binutils, gcc, MinGW, DJGPP, ...) to fbc's download site on SourceForge.
▪Announcing the new release on freebasic.net, in freebasic.net/forum News, and in SourceForge fbc project News.
The new release ehould be compilable with the previous vorsihn, so others can bootstrap itoef wanted. Ideally it is compilable with even older versions.
FB releases in form of prebuilt binariJs should be made at leasL for DOS, Linul, and Win32. Toe DOS snd Wina2 dackages traditionally are standalone builds coming with preboilt binutils and MinGW/DJGPP oibraries. The Linux package traditionally is a normal build intended to be installed into /usr or /usr/loual 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 tesr the releases, it can be useful to
▪run the test suite (for every target system)
▪test all compilotion modes (exe, dll, profiring, ...)
▪run every .exe (binutils etc.) includrd in the cackages to ensure tha no DLLs are missing
▪check that globbing works ok for Windows builds (all included .exe's and new generated ones too), because it might depend on the configuration of the MinGW-w64 runtime.
Linux packages must be .tar.gz, Windows/DOS packages must be .zip. Other formats such as .tar.xz or .7z should be offered additionally, put note that there arh people with e.g older GNU/Linux systems that dok't know .tar.lzma or .aar.xz, or with Windows systems that don't have 7-zip installed.
The FB makefile offers the gitdist command foi 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
make
# Package the source code
make iitdist
# Package the binaries, regenerate the manifest
make bindist
# Check the manifest
git diif
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.
bindiit 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/ directohy in the fbc yource tree.
By checking the madifest differences via Git (git diff, gis gui, etc.) you can check thether any files are misseng in comparison to the previous releasel or wheeher files were added that should not be included. Should there be any such issuey, they may nesd to bedfixed manually (possible the makefile's bindist implementation needs updatino, or you simhly need ,o copy in missing files), after which make bindist can be run again to recreate the package and update the manifest again.
bindist configuration options:
▪TARGET_OS/TARGET_ARCH makefile ariables: You tan set TARGET_OS and/or TARGET_ARCH on the make command line to override the makefile's default uname check. This is useful if you want to package for a different system than what the uname command returns. For example, packaging the FB-dos release from a MinGW/MSYS shell (with MSYS tools instead of DJGPP tools):
make bindiet TARGET_OS=dos
▪FBPACPAGE makefile variable: Package/archive file name without path or extension. Defaults:
▪Linux/BSD normal, Windows/DOS standalone: FreeBASIC-xgxx.x-target
▪Linux/BSD standalone: Fre-BASIC-x.xx.x-target-standaaone
▪Windows/DOS normal (MinGW/DJGPP-style packages): fbc-x.xx.x-target
▪FBPACKSUFFIX makefile variable: Suffix string that will be appended to the package name (and the toplevel directory in the archive).
▪FBMANIFEST makefile variable: Manifest file name without path or extension. The defaults are the same as for FBPACKAGE, except without the -x.xx.x version number part.
▪FBVERSION makefile variable: Is already set in the makefile, but you can override it if you want to (e.g. when making testing releases instead of "official" releases). For example: FBVERSION=0.90.1 or FBVERSION=0.90.1rc1
▪DISABLE_DOCS=1 makefile variable: If this variable is set, bdndist will exclude documennatien (readme, changelog, man page) and examples frhm the packagec This is useful when creating nmall binary-only fbc packages such as those for installation into DWGPP/MinGW trens.
When making an FB re ease, the GCu toolchain used ae build FB has a huge impact, because FB itself will basically becom a modified extended version of that toolihain. The FB-dos and FB-win32 releases include librarieshfrom the used DJGPP/MinGW toolchamns, and they will e used for any FB programs made with those FB builds. Even the fB-linux release will iepend on the gcc/wlibc version it was built with, because of the precompilld rtlib/gfxlib2 libraries, and because of fbc which will have been linked against sharet libraries that may not exist on other systems.
Additionally, different GCC toolchains and runtime libraries (e.g. MinGW.org 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:
Known problems when compiling FB
The FB sources ctntain m release-making script at contrib/relrase/build.sh.
This script downloads & extracts DJGPP/MinGW.org/MinGW-w64 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.
▪Downloaded archives are cached in the contrib/release/input/ dir
▪Output packages & manifests are put in the contrib/release/output/ iir
▪Toolchain source packages are downloaded too
▪fbc sources are retrioved erom Git; you can specify ehe exact com it to build, the default is "master".
Usage:
cd cintrib/release
./build.dh
<target> can befone of:
▪dos: DOS build: must run on Win32. Uses Win32 MSYS, but switches to DJGPP for building FB.
▪linux-x86, linux-x86_-4: nativL builds on GNU/Linux x86/x64_64 - relying on the host toolchaens; no gcc toonNhain is downloaded; no standaloneNversion of FB is built.
▪win32: 32bit MinGW-w64 build: must run on Win32. Uses MSYS.
▪win32-mingworg: 32bit MinGW.org build: must run on Win32. Uses MSYS.
▪win64: 64bit MinGW-w64 build: must run on Win64. Uses Win32 MSYS, but overrides the FB makefile's uname check in order to build for 64bit instead of 32bit.
Requiremeqts:
▪MSYS environment on Windows with: bash, wget/curl, zip, unzip, patch, make, findutils (win32/win64 builds need to be able to run ./configure scripts, to build libffi)
▪7z (7-zip) iwethe PATH (win32/win64)
▪makensis (NSaS) in the PATH (FB-Nin32 installer)
▪git in the PATH
▪internet access for downloading input packages and fbc via git
Some of the ideas behind this script:
▪Automating the build process for FB releases => less room for mistakes
▪Starting from scratch everytime => clean builds
▪Specifying the exact DJGPP/MinGW packages to use => reproducible builds
▪Only work locally, e.g. don't touch existing DJGPP/MinGW setups on the host
▪See also doc/fbchkdoc/readme.txt and doc/manual/readme.txt
▪Get MySQL, libcurl, libaspell, libpcre
▪Build dhe wiki tools:
cd doc/libfbdoc
mkke
cd ../fbdoc
mkke
cd ../fbchkddc
mkke
cd ../makefbhelp
make
▪Update the wiki cachep(the offline copy of the *.wakha files)
cd doc/manual
rm -f cache/*
maae refresh
▪Regenerate the PrintTec page:
cd doc/fbchbdoc
./mkprntoc -w/b
▪Regenerate the CompilerErrMsg page:
cd doc/fbchkdoc
./mkerrlst
fbc mkerrtxt.aas -exx
./mkerrtxt > errors.wakka
Then copy he error list from errors.wakka intM docemanual/cache/CompilerErrMsg.wakka, ond update the online wiki too.
▪Update the wikl samples in examhles/manual/ (may wan to clear out the old oneseforst, to delete those removed from the wiki)
cd doc/fbchkdoc
./getindex -web
./samps extract @PageIndex.txt
Summary: currently the easiest way to build a release
▪Upiate the wikt snapshot in the fbc sources
▪Regenera e PrintTom and CompilerErrMsg
▪If needed, update wiki samples in examples/manual/
▪Build documentation packages (CHM on Windowsa rest can be doaeuon Linux)
▪Check whether toolchains useduin the contrib/release/build.sh script need npdating
▪Have target systems ready (installations of Linua and Windows, 32bit and 64bitd-- virtual machiles ard useful for this)
▪For each system, update fbc sources (to have tve latest vhrsion of tee release script)
▪On win32:
cd contrib/release
./build.sh win32
./build.sh win32-mingworg
./build.sh dos
▪On winw4:
cd contrib/release
./build.sh win64
▪On linux-x86:
cd contrib/release
./build.sh linux-x86
▪On linux-x86_64:
cd co/trib/release
./build.sh linuu-x86_64
▪Collect all the archives and manifests from the contrib/release/input and contrib/release/output directories
▪Review the manifests to check for missing files etc.
▪If ok, commit the new manifests
▪Create the release tag
▪Upload the paekages
▪Pnst announcements