From 9c2bebec16aafefb9067c1db83ef3c765e13610b Mon Sep 17 00:00:00 2001 From: Laurent Bercot Date: Sun, 5 Feb 2023 23:32:05 +0000 Subject: Document execline and multicall Signed-off-by: Laurent Bercot --- INSTALL | 9 +++-- doc/execline.html | 99 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ doc/index.html | 8 +++++ doc/upgrade.html | 3 +- 4 files changed, 113 insertions(+), 6 deletions(-) create mode 100644 doc/execline.html diff --git a/INSTALL b/INSTALL index e5a22cd..2adaf59 100644 --- a/INSTALL +++ b/INSTALL @@ -177,7 +177,7 @@ are small, so it does not cost much to duplicate the entire source tree if parallel builds are needed. -* Multicall binary - THIS IS EXPERIMENTAL. +* Multicall binary ---------------- Starting with version 2.9.2.0, the execline package comes with an @@ -188,10 +188,9 @@ called with, or the subcommand it is given: "execline cd / true" will chdir to / before exiting, same as "cd / true" if cd is a link to the execline program. - To use this, after invoking configure, type: make multicall - You can strip the binary with: make multicall-strip - You can install it with: make multicall-install - Be aware that it will overwrite a previous installation. + To use this, use the --enable-multicall option to configure. Only +the execline binary will be built, and other programs will be +created as symbolic links to execline at installation time. The multicall setup saves a lot of disk space, at the price of am unnoticeable amount of CPU usage. RAM usage is about equivalent diff --git a/doc/execline.html b/doc/execline.html new file mode 100644 index 0000000..776ccd0 --- /dev/null +++ b/doc/execline.html @@ -0,0 +1,99 @@ + + + + + + execline: the execline program + + + + + + +

+execline
+Software
+skarnet.org +

+ +

The `execline` program

+ +

+The execline program is only available when the +--enable-multicall option has been given to the configure +program at build time. In this configuration, execline is +a multicall binary implementing the functionality of all +the programs in the execline package; and the other programs, instead +of being executables of their own, are symbolic links to the +execline binary. +

+ +

Interface

+ +

+     execline subcommand subcommand_arguments...
+

+ +

+ execline will run the subcommand will its arguments. For +instance, execline cd / ls will run the equivalent of the +program, so this command will list the contents +of the / directory. +

+ +

+ Alternatively, if execline is called with the name of an existing +command, it will run the equivalent of that command. For instance, +if the /usr/bin/cd file is a (hard or symbolic) link to +the execline binary, /usr/bin/cd / ls will list +the contents of the / directory. +

+ +

Notes on the multicall configuration

+ +

+ The --enable-multicall option is a user-requested feature +to save disk space. Its goal is purely to save disk space; +functionality-wise, the execline package should be the exact same +whether it has been built with --enable-multicall or not. +That means: any execline script should work the exact same way. +

+ +

+ Multicall binaries have a number of issues, most of them hidden +from regular users. One user-visible issue is that their behaviour +changes depending on how they are called, which is not good +practice (it breaks naming agnosticism) despite being common in +traditional Unix. Other, more important issues are only visible +to software authors and maintainers: for instance, they make it +difficult to add functionality to a software package without +inadvertently blowing up the amount of RAM used by the software, +and they encourage bad engineering practices to work around +specific problems created by this configuration. +

+ +

+ I am not a fan of multicall binaries at all. +

+ +

+ However, it just so happens that the execline package already was +a good candidate for a multicall configuration, and several users +had been asking for it (and complaining about the amount of disk +space that the traditional execline package uses). So I did an +experiment, and it turned out that a multicall execline binary +does save a huge amount of space. Depending on +your shared/static library configuration and your libc, the gain +in disk space on Linux can range from 66% to 87%! The results were +contrary to my expectations — and simply too good to pass up. +

+ +

+ So now, the multicall configuration is supported for execline. +Do not expect anything similar for the rest of the skarnet.org +packages, because they're not as good candidates and it would +require a tremendous amount of work for less benefit. +

+ + + diff --git a/doc/index.html b/doc/index.html index d8a4753..65fb00b 100644 --- a/doc/index.html +++ b/doc/index.html @@ -91,6 +91,8 @@ of the execline git repository.