Fossil: Compiling and Installing Fossil

0.0 Using A Pre-compiled Binary

Pre-compiled binaries are available for recent releases. Just download the appropriate executable for your platform and put it on your $PATH. To uninstall, simply delete the executable. To upgrade from an older release, just overwrite the older binary with the newer one.

0.1 Executive Summary

Building and installing is very simple. Three steps:

Download and unpack a source tarball or ZIP.
./configure; make
Move the resulting "fossil" or "fossil.exe" executable to someplace on your $PATH.

1.0 Obtaining The Source Code

Fossil is self-hosting, so you can obtain a ZIP archive or tarball containing a snapshot of the latest version directly from Fossil's own fossil repository. Additionally, source archives of released versions of fossil are available from the downloads page. To obtain a development version of fossil, follow these steps:

Point your web browser to https://fossil-scm.org/
Click on the Timeline link at the top of the page.
Select a version of of Fossil you want to download. The latest version on the trunk branch is usually a good choice. Click on its link.
Finally, click on one of the "Zip Archive" or "Tarball" links, according to your preference. These link will build a ZIP archive or a gzip-compressed tarball of the complete source code and download it to your computer.

Aside: Is it really safe to use an unreleased development version of the Fossil source code?

Yes! Any check-in on the trunk branch of the Fossil Fossil self-hosting repository will work fine. (Dodgy code is always on a branch.) In the unlikely event that you pick a version with a serious bug, it still won't clobber your files. Fossil uses several self-checks prior to committing any repository change that prevent loss-of-work due to bugs.

The Fossil self-hosting repositories, especially the one at http://fossil-scm.org/home, usually run a version of trunk that is less than a week or two old. Look at the bottom left-hand corner of this screen (to the right of "This page was generated in...") to see exactly which version of Fossil is rendering this page. It is always safe to use whatever version of the Fossil code you find running on the main Fossil website.

2.0 Compiling

Unpack the ZIP or tarball you downloaded then cd into the directory created.
(Optional, Debian-compatible Linux only) Make sure you have all the necessary tools and libraries at hand by running: sudo apt install tcl-dev tk libssl-dev.
(Optional, Unix only) Run ./configure to construct a makefile.
1. The build system for Fossil on Unix-like systems assumes that the OpenSSL development and runtime files are available on your system, because unprotected repositories are trivial to attack otherwise. Indeed, some public Fossil repositories — including Fossil's own — today run in an HTTPS-only mode, so that you can't even do an anonymous clone from them without using the TLS features added to Fossil by OpenSSL. To weaken that stance could allow a man in the middle attack, such as one that substitutes malicious code into your Fossil repository clone.
  
  You can force the Fossil build system to avoid searching for, building against, and linking to the OpenSSL library by passing --with-openssl=none to the configure script.
  
  If you do not have the OpenSSL development libraries on your system, we recommend that you install them, typically via your OS's package manager. The Fossil build system goes to a lot of effort to seek these out wherever they may be found, so that is typically all you need to do.
  
  For more advanced use cases, see the OpenSSL discussion in the "TLS and Fossil" document.
2. To build a statically linked binary (suitable for use inside a chroot jail) add the --static option.
3. To enable the native Tcl integration feature feature, add the --with-tcl=1 and --with-tcl-private-stubs=1 options.
4. Other configuration options can be seen by running ./configure --help
Run "make" to build the "fossil" or "fossil.exe" executable. The details depend on your platform and compiler.
1. Unix → the configure-generated Makefile should work on all Unix and Unix-like systems. Simply type "make".
2. Unix without running "configure" → if you prefer to avoid running configure, you can also use: make -f Makefile.classic. You may want to make minor edits to Makefile.classic to configure the build for your system.
3. MinGW 3.x (not 4.x) / MinGW-w64 → Use the MinGW makefile: "make -f win/Makefile.mingw". On a Windows box you will need either Cygwin or MSYS as build environment. On Cygwin, Linux or Darwin you may want to make minor edits to win/Makefile.mingw to configure the cross-compile environment.
  To enable the native Tcl integration feature, use a command line like the following (all on one line):
  make -f win/Makefile.mingw FOSSIL_ENABLE_TCL=1 FOSSIL_ENABLE_TCL_STUBS=1 FOSSIL_ENABLE_TCL_PRIVATE_STUBS=1
  Alternatively, ./configure may now be used to create a Makefile suitable for use with MinGW; however, options passed to configure that are not applicable on Windows may cause the configuration or compilation to fail (e.g. fusefs, internal-sqlite, etc).
  HINT: Do not use MinGW-4.x, it may compile but the Fossil binary will not work correctly, see ticket.
4. MSVC → Use the MSVC makefile.
  Run all of the following from a "x64 Native Tools Command Prompt".
  First change to the "win/" subdirectory ("cd win") then run "nmake /f Makefile.msc".
  
  Alternatively, the batch file "win\buildmsvc.bat" may be used and it will attempt to detect and use the latest installed version of MSVC.
  
  To enable the optional OpenSSL support, first download the official source code for OpenSSL and extract it to an appropriately named "openssl" subdirectory within the local compat directory then make sure that some recent Perl binaries are installed locally, and finally run one of the following commands:
```
nmake /f Makefile.msc FOSSIL_ENABLE_SSL=1 FOSSIL_BUILD_SSL=1 PERLDIR=C:\full\path\to\Perl\bin
```
```
buildmsvc.bat FOSSIL_ENABLE_SSL=1 FOSSIL_BUILD_SSL=1 PERLDIR=C:\full\path\to\Perl\bin
```
  To enable the optional native Tcl integration feature, run one of the following commands or add the "FOSSIL_ENABLE_TCL=1" argument to one of the other NMAKE command lines:
```
nmake /f Makefile.msc FOSSIL_ENABLE_TCL=1
```
```
buildmsvc.bat FOSSIL_ENABLE_TCL=1
```
5. Cygwin → The same as other Unix-like systems. It is recommended to configure using: "configure --disable-internal-sqlite", making sure you have the "libsqlite3-devel" , "zlib-devel" and "openssl-devel" packages installed first.

3.0 Installing

The finished binary is named "fossil" (or "fossil.exe" on Windows). Put this binary in a directory that is somewhere on your PATH environment variable. It does not matter where.
(Optional:) To uninstall, just delete the binary.

4.0 Additional Considerations

If the makefiles that come with Fossil do not work for you, or for some other reason you want to know how to build Fossil manually, then refer to the Fossil Build Process document which describes in detail what the makefiles do behind the scenes.
The fossil executable is self-contained and stand-alone and usually requires no special libraries or other software to be installed. However, the "--tk" option to the diff command requires that Tcl/Tk be installed on the local machine. You can get Tcl/Tk from ActiveState.

To build on older Macs (circa 2002, MacOS 10.2) edit the Makefile generated by configure to add the following lines:

  TCC += -DSQLITE_WITHOUT_ZONEMALLOC
  TCC += -D_BSD_SOURCE
  TCC += -DWITHOUT_ICONV
  TCC += -Dsocketlen_t=int
  TCC += -DSQLITE_MAX_MMAP_SIZE=0

5.0 Building a Static Binary on Linux using Docker

Building a static binary on Linux is not as straightforward as it could be because the GNU C library requires that certain components be dynamically loadable. That can be worked around by building against a different C library, which is simplest to do by way of a container environment like Docker.

The following instructions for building fossil using Docker were adapted from forumpost/5dd2d61e5f. These instructions assume that docker is installed and that the user running these instructions has permission to do so (i.e., they are root or are a member of the docker group).

First, create a file named Dockerfile with the following contents:


# Alpine >3.13 breaks stuff on many host OSes! For details see:
# https://wiki.alpinelinux.org/wiki/Draft_Release_Notes_for_Alpine_3.14.0#faccessat2
# FROM    alpine:edge
FROM    alpine:3.13
RUN     apk update                                                                                      \
        && apk upgrade                                                                                  \
        && apk add --no-cache                                                                           \
        curl gcc make tcl                                                                               \
        musl-dev                                                                                        \
        openssl-dev zlib-dev                                                                            \
        openssl-libs-static zlib-static                                                                 \
        && curl                                                                                         \
        "https://fossil-scm.org/home/tarball/fossil-src.tar.gz?name=fossil-src&uuid=trunk"    \
        -o fossil-src.tar.gz                                                                            \
        && tar xf fossil-src.tar.gz                                                                     \
        && cd fossil-src                                                                                \
        && ./configure                                                                                  \
        --static                                                                                        \
        --disable-fusefs                                                                                \
        --with-th1-docs                                                                                 \
        --with-th1-hooks                                                                                \
        && make

Be sure to modify the configure flags, if desired. e.g., add --json for JSON support.

From the directory containing that file, build it with docker:

# docker build -t fossil_static .

If you get permissions errors when running that as a non-root user, be sure to add the user to the docker group before trying again.

That creates a docker image and builds a static fossil binary inside it. That step will take several minutes or more, depending on the speed of the build environment.

Next, create a docker container to host the image we just created:

# docker create --name fossil fossil_static

Then copy the fossil binary from that container:

# docker cp fossil:/fossil-src/fossil fossil

The resulting binary will be huge because it is built with debug info. To strip that information, reducing the size greatly:

# strip fossil

To delete the Docker container and image (if desired), run:

# docker container rm fossil
# docker image ls

Note the IDs of the images named fossil_static and alpine, then:

docker image rm THE_FOSSIL_ID THE_ALPINE_ID

6.0 Building on/for Android

6.1 Cross-compiling from Linux

The following instructions for building Fossil for Android, without requiring a rooted OS, are adapted from forumpost/e0e9de4a7e.

On the development machine, from the fossil source tree:

export CC=$NDK_PATH/toolchains/llvm/prebuilt/linux-x86_64/bin/armv7a-linux-androideabi21-clang
./configure --with-openssl=none
make

On the Android device, enable the USB debugging option from Developer menu in Device Options. Connect the device to the development system with USB. If it's configured and connected properly, the device should show up in the output of adb devices:

sudo adb devices

Copy the resulting fossil binary onto the device...

sudo adb push fossil /data/local/tmp

And run it from an adb shell:

sudo adb shell
> cd /data/local/tmp
# Fossil requires a HOME directory to work with:
> export HOME=$PWD
> export PATH=$PWD:$PATH
> fossil version
This is fossil version 2.11 [e5653a4ceb] 2020-03-26 18:54:02 UTC

The output might, or might not, include warnings such as:

WARNING: linker: ./fossil: unused DT entry: type 0x6ffffef5 arg 0x1464
WARNING: linker: ./fossil: unused DT entry: type 0x6ffffffe arg 0x1ba8
WARNING: linker: ./fossil: unused DT entry: type 0x6fffffff arg 0x2

The source of such warnings is not 100% certain. Some information about these (reportedly harmless) warnings can be found on this StackOverflow post.