nilfs-utils/README

* Required packages

 - libuuid-devel or uuid-dev
 - libmount-devel or libmount-dev
 - libblkid-devel or libblkid-dev
 - libselinux-devel or libselinux1-dev (*1)
 - pkg-config (*2)

 *1: required only if supporting SELinux context mount options without
     using libmount.  By default, libmount is used and support of the
     context mount depends on the libmount that distro provides.

 *2: required if resolving build dependencies via .pc (pkg-config)
     files or generating the project's .pc files.


* How to compile

** From a source package (tarball): **

 $ ./configure
 $ make

** From the git repository: **

 $ git clone https://github.com/nilfs-dev/nilfs-utils.git
 $ cd nilfs-utils
 $ ./autogen.sh
 $ ./configure
 $ make

Before compiling the development sources (git clone), you need to run
the autogen.sh script to generate the configuration files.  This is not
required for packaged sources unless you have modified build system
files such as configure.ac or Makefile.am.


* Installation

To install the compiled utilities and libraries to your system, run:

 $ sudo make install

To remove the installed files from your system, you can run:

 $ sudo make uninstall

Note: It is recommended to keep the build directory or the original
source tree if you plan to use 'make uninstall' later, as it relies
on the Makefile generated during configuration.

For more detailed general instructions, see the automatically
generated INSTALL file.


* Installation path configuration

The configure script automatically probes your system to determine the
appropriate library installation directory (libdir).

- On systems using RPM-based package management (e.g., RHEL clones,
  Fedora, openSUSE):
  Detects and sets libdir according to the system's library macro
  (typically /usr/lib64 on 64-bit systems).

- On Debian-based distributions (e.g., Debian, Ubuntu, etc):
  Detects and sets libdir according to the Multiarch specification
  (e.g., /usr/lib/x86_64-linux-gnu).

You can manually override this detection using the --libdir option:

 $ ./configure --libdir=/usr/lib64

The configure script can also generate pkg-config files (.pc files)
that provide build metadata for other tools or applications that
utilize nilfs-utils libraries.  The following option is available to
control the installation of these files:

 $ ./configure --with-pkgconfigdir=DIR

If the DIR parameter (which is to specify the directory for
pkg-config files) is omitted, the path will be auto-detected (usually
${libdir}/pkgconfig).  To disable the installation of .pc files, set
it to 'no' or use --without-pkgconfigdir option.

Modern Linux distributions follow the "UsrMerge" or "Bin-Sbin merge"
schemes.  The configure script automatically detects the system
hierarchy and adjusts the installation paths for core binaries
(mkfs.nilfs2, mount.nilfs2, nilfs_cleanerd, etc.):

 - Legacy: Installs to /sbin
 - UsrMerge: Installs to /usr/sbin
 - Bin-Sbin merge (e.g., Fedora Rawhide): Installs to /usr/bin

When installing to /usr/bin, the build system also attempts to create
compatibility symbolic links in /usr/sbin if that directory exists and
is different from /usr/bin.

You can manually override this detection using the following options:

 # Force installation into /usr/bin (Bin-Sbin merge style)
 $ ./configure --enable-usrmerge=bin

 # Force installation into /usr/sbin (UsrMerge style)
 $ ./configure --enable-usrmerge=sbin

 # Force installation into the traditional /sbin
 $ ./configure --disable-usrmerge

By default, if the option is omitted, the script probes the system's
directory configuration to determine the appropriate hierarchy.  If
the option is specified without a TYPE (i.e., --enable-usrmerge), it
defaults to "sbin" (/usr/sbin) to align with standard UsrMerge
practices.

Note: This option is significant even when /sbin is a symbolic link to
/usr/sbin (i.e., the physical installation destination is the same).
It ensures that the absolute paths used by the utilities to call other
binaries are consistent with the chosen hierarchy.


* Build dependency information (pkg-config)

Since version 2.3.0, nilfs-utils provides pkg-config metadata files
for its shared libraries (nilfs.pc and nilfsgc.pc).  These files are
intended to simplify the development of independent tools that link
against nilfs-utils libraries, and typical users do not need to be
aware of them.

For those interested in using these files for development, please
refer to the pkg-config(1) manual page or its official documentation
(https://www.freedesktop.org/wiki/Software/pkg-config/).


* Cross-compilation and remote deployment

When cross-compiling, automatic library directory detection is
disabled.  You must explicitly specify the target's library directory.
Additionally, you should specify the UsrMerge scheme of the target
system to ensure files are installed to the correct locations.

1. Preparation (e.g., for aarch64/arm64 on Ubuntu noble):
   You need a cross-toolchain and development libraries for the target
   architecture.  On a Debian-based host, you can set them up as
   follows:

    $ sudo dpkg --add-architecture arm64
    $ sudo apt update
    $ sudo apt install gcc-aarch64-linux-gnu libuuid1:arm64 \
        libblkid-dev:arm64 libmount-dev:arm64 libselinux1-dev:arm64

   If you are on Ubuntu, you may need to add the ports repository to
   /etc/apt/sources.list.d/ubuntu.sources (or your sources.list):

    Types: deb
    URIs: http://ports.ubuntu.com/ubuntu-ports
    Suites: noble noble-updates noble-security noble-backports
    Components: main restricted universe multiverse
    Signed-By: /usr/share/keyrings/ubuntu-archive-keyring.gpg
    Architectures: arm64

   For more details, please refer to the cross-compilation guidelines
   provided by your specific distribution.

2. Configure and build:
   For example, when cross-compiling for aarch64-linux-gnu machine
   running a UsrMerge-enabled OS:

    $ ./configure --host=aarch64-linux-gnu \
        --libdir=/usr/lib/aarch64-linux-gnu \
        --enable-usrmerge=sbin
    $ make

3. Install to target:
   Instead of running 'make install' on the target, it is recommended
   to use DESTDIR on the host and transfer the files:

    $ make install DESTDIR=$HOME/tmp/aarch64-linux-root
    $ tar czf - -C $HOME/tmp/aarch64-linux-root . | \
        ssh target-host "sudo tar xzvf - --no-same-owner -C /"

   Here, "target-host" represents the host you want to deploy to.
   Using --no-same-owner with sudo on the target ensures that the
   extracted files are owned by the root user.

   After transferring the files, update the shared library cache on
   the target system:

    $ ssh target-host "sudo ldconfig"


* Troubleshooting

If you change the installation path (such as --libdir) or other
configuration options, old build artifacts (especially libtool's .la
files) may cause build or installation errors.  In such cases, perform
a clean build as follows:

 $ make distclean
 $ ./configure [your-new-options]
 $ make

If you have:

 - Updated the source tree (e.g., 'git pull')
 - Installed/Uninstalled system tools (e.g., pkg-config) or libraries
 - Encountered "command not found" or strange autoconf errors

Stale caches (like autom4te.cache) or outdated generated files may
be the cause.  In such cases, perform a full reset using git:

 $ git clean -xdf
 $ ./autogen.sh
 $ ./configure [options]
 $ make

 WARNING: This will delete ALL untracked files, including your local
 config files or uncommitted changes.

If the blkid library in your environment is old and incompatible with
this package, you can use --without-blkid option:

 $ ./configure --without-blkid

However, use of this option is normally not recommended because it
disables the safety check of mkfs.nilfs2, which prevents users from
accidentally overwriting an in-use device.

If /etc/mtab is not a symlink to /proc/self/mounts but a regular file
in the target system, you may need to disable libmount support to
properly handle the legacy mtab file:

 $ ./configure --without-libmount

This option is primarily intended for legacy environments or
specialized configurations that still rely on a writable /etc/mtab
file.  Note that most modern distributions provide libmount as standard
and do not require this option.

You can compile the legacy mount.nilfs2 and umount.nilfs2 helpers
without support for SELinux context mount options (-o context=<context>,
etc):

 $ ./configure --without-libmount --without-selinux

For helpers built with mount library (libmount), support of the
context mount depends on the libmount that distro provides.

If you are having problems due to the missing nilfs2 disk format or
ioctl interface definition file (nilfs2_ondisk.h or nilfs2_api.h,
respectively), try installing the Linux kernel source or header file
package first.

If you still cannot install these files, or if you want to overwrite
them with files from this package, specify the
"--enable-uapi-header-install" option as an argument to the configure
script.  This will install the uapi header files included in this
package:

 $ ./configure --enable-uapi-header-install

Note that the utility package itself references bundled local header
files, so you don't need to install these files with this option to
build.


* Developer's notes

The central resource for nilfs-utils development is the mailing list
(linux-nilfs@vger.kernel.org).

First, please read the following documents (in short, follow Linux
kernel development rules):

https://docs.kernel.org/process/coding-style.html
https://docs.kernel.org/process/submitting-patches.html

Then, check your patches with the patch style checker prior to
submission (scripts/checkpatch.pl) like the following example:

 $ ./scripts/checkpatch.pl <patch-file>
 ...
 <patch-file> has no obvious style problems and is ready for submission.