Escaped symbols for GNU Make

This project enables a GNU Makefile to use characters that require
special escaping techniques.

Testing

To view a list (more like unicode ASCII-art table) of all the variables that
export the escaped symbols, run make or make test.

Debugging

There is not much to debug when it comes to Makefiles, but I have added a few
$(info) messages that allow you to debug how the project is loaded (inclusion
order) or if it is loaded at all. To enable these debug messages set the
variable MK_ESCAPE_DEBUG to 1, either when testing this project or when
using make with any other project that includes this library.

Runtime dependencies

The only program required during the execution of a Makefile (parsing phase, not
the recipe execution phase) is echo, which is used to escape the backslash
symbol (\).

Compilation dependencies

When it comes to testing, installing and uninstalling, this project depends on a
set of programs that are very likely installed in your system, specially on
POSIX/UNIX-like systems.

The list of development dependencies are:

• make: the build system; used for everything.
• printf: used to create the export profile and print same-length strings;
  used during testing installation.
• test: used to check the existence of directories, files and symbolic links;
  used during installation and uninstallation.
• mkdir: used to create directories; used during installation.
• install: used to install files; used during installation.
• sed: used to fix the installed make-escape.mk file; used during
  installation.
• ln: used to create symbolic links; used during installation.
• rm: used to remove files and symbolic links; used during uninstallation.
• rmdir: used to remove directories; used during uninstallation.

Installation

Performing an installation directly from the sources is as easy as installing
any autotools-based project, except this one does not use autotools at all, so
there is no configure script. The full installation command is:

make install DESTDIR=''                     \
             PREFIX='/usr/gnu'              \
             INCLUDEDIR='$(PREFIX)/include' \
             SYSCONFDIR='/etc'              \
             ENABLE_PROFILED_EXPORT=yes

The variables passed as arguments to make allow configuring some aspects of
the installation process (the values shown are the default values if no
variables are passed as arguments).

• DESTDIR: The path without trailing slash used as root of the installation
  file tree. It should be used in certain scenarios such as packaging.
• PREFIX: The prefix used to build the rest of the paths; defaults to
  /usr/gnu instead of /usr, because it works only with GNU make.
• INCLUDEDIR: The directory path where the include files will be installed to;
  defaults to $(PREFIX)/include.
• SYSCONFDIR: The directory path where the configuration files will be
  installed to /etc.
• ENABLE_PROFILED_EXPORT: Enables (yes) or disables (no) the installation
  of the profile script /etc/profile.d/make-escape.sh that automatically
  exports the MK_ESCAPE_ROOT variable. Beware that the check uses the
  constant no for comparisons, which means that any value that is not
  literally no is equivalent to yes.

Source and binary RPM packages

The project itself hosts the source and binary RPM packages, which are deployed
automatically when pushing to the rpm branch (along with the SHA-256 checksum
files), under the releases section.

openSUSE Build Service

This project is also published in my personal OBS project home:egasato.
I update it right after I change anything in this repository so that it can be
installed easily with zypper, and to recompile it automatically whenever any
of its dependencies are updated. You can import the repository to receive
automatic updates not only for openSUSE but also for other distributions.

Source and binary Pacman packages

The project itself hosts the source and binary Pacman packages, which are
deployed automatically when pushing to the pacman branch (along with the
SHA-256 checksum files), under the releases section. These packages
may not be signed, but if they are it means I created them personally, because
my policy is not to sign the artifacts produced by CI/CD services unless I own
the machine, which is not the case here.

Arch Linux User Repository

The PKGBUILD from the pacman branch is also published in its own AUR
repository, so that you can install it easily using pacman wrappers such as
yay.

Usage

1. This project can be used in the source code form or as an installed library.
   Follow the installation steps (and remember the installation path, which by
   default is /usr/gnu/include/make-escape) or clone the repository somewhere
   where you can access it (a Git submodule is also a valid option).

2. The second step is to create your own Makefile and conditionally define
   (?=) a variable named MK_ESCAPE_ROOT pointing to the root path of the
   library with a trailing slash (for the default installation path that would
   be /usr/gnu/include/make-escape/) or do not define it and assume it is
   installed. The path MUST be valid and MUST be either absolute or relative to
   the root Makefile, otherwise make will not know how to resolve it.

MK_ESCAPE_ROOT ?= /usr/gnu/include/make-escape/

1. The second and last step is to include the system library loader
   ($(MK_ESCAPE_ROOT)make-escape.mk). If the variable is not defined it
   will try to include make-escape.mk, which will fallback to the system
   include directories (<prefix>/include, /usr/gnu/include,
   /usr/local/include or /usr/include) and find the library if it is
   installed somewhere there; otherwise it will load the library correctly
   (assuming you shipped it as a dependency). Both library loaders will define
   the MK_ESCAPE_ROOT variable and load the library-specific library loader
   ($(MK_ESCAPE_ROOT)main.mk), which will load the rest of the files if it
   knows where it is installed. This means that if this execution point is
   reached and the variable MK_ESCAPE_ROOT is not defined it will exit
   prematurely and print the error, because there is no way a non-primary
   Makefile (a Makefile that has been included) can include another file with a
   path relative to itself without using an auxiliary variable
   (MK_ESCAPE_ROOT in this case).

include $(MK_ESCAPE_ROOT)make-escape.mk

Known issues

As far as I know it has no known issues, except that a linefeed cannot be
printed inside a recipe without using the .ONESHELL special target.

Signing policy

I will not sign any archive, tarball or package unless one of these conditions
is true:

1. I personally created the archive/tarball/package in a machine of my property.
2. I did not personally create the archive/tarball/package in a machine of my
   property, but the signature is required for something else (e.g. verifying
   the sources when creating Arch Linux packages). This means I reviewed the
   contents and I am 100% sure they are safe, therefore I sign only files that
   are human-readable or contain only human-readable files (e.g. source
   tarballs).

You can download my GPG keys from the repository egasato/gpg.