bookmarkfs/INSTALL.md

Requirements

Operating System

Currently, BookmarkFS runs on the following operating systems:

• GNU/Linux
• FreeBSD (with caveats)

See the user manual for comments if you wish to port BookmarkFS to other operating systems.

Dependencies

In addition to the OS kernel and a POSIX-compatible libc, BookmarkFS depends on a few third-party libraries:

Library Name	Minimal Version
libfuse	3.5
libseccomp	2.5
SQLite	3.35
Jansson	2.14
Nettle	3.4
GNU Readline	6.0
Tcl	8.6
uriparser	0.9
xxHash	0.8

Some of them can be optional, depending on which components of BookmarkFS are to be built, and which features are enabled.

Build Tools

• The GNU build system
  • Autoconf
  • Automake
  • Libtool
  • Autoconf Archive
• pkg-config
• POSIX-compatible make
  • One with VPATH support is recommended
• C99-capable C compiler
  • GCC or Clang is recommended

Optionally:

• GNU Texinfo
  • For building the user manual

Installation

Configure Build

Select a build directory and generate configuration scripts:

$ mkdir build && cd build
$ autoreconf -i ..

To list all available configuration options, run:

$ ../configure --help

BookmarkFS has multiple components. By default, none will be built. Except for the utility library, each component can be enabled independently:

• The BookmarkFS utility library: --enable-bookmarkfs-util
  • Requires: libseccomp (Linux-only), xxHash
  • Automatically enabled if required by other components
• The mount.bookmarkfs program: --enable-bookmarkfs-mount
  • Requires: libfuse, bookmarkfs-util
• The fsck.bookmarkfs program: --enable-bookmarkfs-fsck
  • Requires: Readline, bookmarkfs-util
• The mkfs.bookmarkfs program: --enable-bookmarkfs-mkfs
• The bookmarkctl program: --enable-bookmarkctl
• The Firefox backend: --enable-backend-firefox
  • Requires: SQLite, Nettle, uriparser, bookmarkfs-util
• The Chromium backend: --enable-backend-chromium
  • Requires: Jansson, Nettle, bookmarkfs-util
• The Tcl-based handler for fsck.bookmarkfs: --enable-fsck-handler-tcl
  • Requires: Tcl

For each of the required third-party libraries, if installed in a custom location, it should be specified with --with-<foo>=<pkgconfdir>, where <foo> is the library name, and <pkgconfdir> is the directory holding its pkg-config file.

Other options:

• --disable-sandbox
  • Build the utility library without sandboxing features
  • No longer requires: libseccomp
• --disable-sandbox-landlock (Linux-only)
  • Disable the Landlock feature in the sandbox implementation
• --enable-xxhash-inline
  • Use xxHash as a header-only library
• --disable-backend-firefox-write
  • Build the Firefox backend without write features
  • No longer requires: Nettle, uriparser
• --disable-backend-chromium-write
  • Build the Chromium backend without write features
  • No longer requires: Nettle
• --enable-boookmarkfs-debug
  • Add more run-time checks and logs for debugging
• --disable-native-watcher
  • Build the file watcher without platform-specific API dependency
• --disable-interactive-fsck
  • Disable interactive features for fsck.bookmarkfs
  • No longer requires: Readline

An example configuration:

$ ../configure --prefix=$HOME/.local  \
>         --enable-bookmarkfs-mount --enable-backend-firefox  \
>         --with-fuse3=$HOME/.local/lib/pkgconfig  \
>         CFLAGS='-O2'

Build and Install

After configuration, build the binaries:

$ make

Run tests:

$ make check

Install the binaries:

$ make install-exec

Install the development headers and the pkg-config file:

$ make install-data

Install the user manual:

$ make install-man install-info

Uninstall:

$ make uninstall

Notes

Linking to an Existing BookmarkFS Utility Library

If a BookmarkFS utility library is already installed, it can be specified with --with-bookmarkfs[=<pkgconfdir>] during configuration, in the same way as with other dependencies.

In this case, the utility library will not be built from source, and other components will link to the specified library instead.

Targeting 32-bit Platforms

BookmarkFS requires 64-bit off_t and time_t, which may not be supported on 32-bit platforms (e.g., i386 FreeBSD does not support 64-bit time_t).

If using Autoconf 2.72 or later, the configuration script automatically performs checks and defines necessary macros, and fails if unsupported. With legacy Autoconf, only off_t is checked.

To manually configure 64-bit time_t, add preprocessor flags -D_TIME_BITS=64 (or something equivalent, depending on the toolchain). If unsupported, make will fail.

FreeBSD and GNU libiconv

NOTE: You may skip this section if not building the Chromium backend.

Before 10.0-RELEASE, the FreeBSD libc did not have a native iconv, and linked to GNU libiconv from the converters/libiconv port. Nowadays, that port is still used by many other ports, thus it is likely to be installed on your system, which could be problematic.

The system iconv.h header is installed as /usr/include/iconv.h, and the libiconv one /usr/local/include/iconv.h. When we #include <iconv.h>, the latter may be chosen by the preprocessor instead of the former, where iconv*() function calls are redefined to libiconv*() ones, which results in "undefined symbols" error since we're not linking to libiconv.

To workaround this issue, you may add preprocessor flags -D_LIBICONV_H -include /usr/include/iconv.h to choose the system iconv, or linker flags -L/usr/local/lib -liconv to choose GNU libiconv.