New Build Documentation

In my ttmrichter branch, tagged newbuild, I have a new build system in the works that should make it easier for new users to quickly get up to speed on their platform of choice. The new system works thusly:

• One Makefile drives all platforms.
• Different platforms are brought into this makefile through include commands. Which one is brought in is specified using a variable called PLATFORM. For example if PLATFORM is set to "solaris" the Makefile will bring in the makefile fragment named ./make/solaris-fragment.mk. This fragment selects which features are enabled and other OS-specific settings. PLATFORM defaults to "linux" if not supplied.
• Different compilers are introduced via the COMPILER variable. For example if you wish to use clang instead of gcc, simply set COMPILER to clang. As with the previous, a makefile fragment build from the compiler name is brought in. This file will set compiler command line options. COMPILER defaults to "gcc" if not supplied.
• As it is a hassle to constantly have to set the variables on the command line, two site-specific configuration makefile fragments are loaded in by the main makefile if present: pre-config.mk and post-config.mk. These files are not under revision control and thus will not interfere with the Fossil source itself.
• ./pre-config.mk is included before PLATFORM or COMPILER are set and is thus a perfect place to define these two variables to avoid the need for convoluted (and error-prone) command lines or for build scripts.
• ./post-config.mk is included after the platform and compiler fragments are executed and is thus a perfect place to override the settings provided in these fragments.
• To support platform-specific modifications of compiler settings, special variables -- PLATFORM_SPECIFIC_(compiler) and PLATFORM_SPECIFIC_LIB are provided. You can see how these variables are set in the ./make/mingw32-fragment.mk file (note the use of a friendlier wrapper definition) and how they are used in the two compiler fragment files.
• Note that since platforms are included before compilers, it is possible for platform fragments to force specific compilers if this is desirable. Again the MinGW32 fragment demonstrates this, forcing the compiler to be GCC.

It is hoped that the new build system will permit new platforms and new compilers to be more quickly supported in a well-regulated way, and that it will make things easier for end-users who have to modify builds based on their sites' idiosyncracies.