diff options
| author | Laurent Bercot <ska-skaware@skarnet.org> | 2023-02-05 23:32:05 +0000 |
|---|---|---|
| committer | Laurent Bercot <ska@appnovation.com> | 2023-02-05 23:32:05 +0000 |
| commit | 9c2bebec16aafefb9067c1db83ef3c765e13610b (patch) | |
| tree | 35d516abd5d3aeb089a8c2b0bc99532bb1ce6a30 /doc | |
| parent | 4676457df2c8a73b4f589a66315b9b137ee89202 (diff) | |
| download | execline-9c2bebec16aafefb9067c1db83ef3c765e13610b.tar.gz execline-9c2bebec16aafefb9067c1db83ef3c765e13610b.tar.xz execline-9c2bebec16aafefb9067c1db83ef3c765e13610b.zip | |
Document execline and multicall
Signed-off-by: Laurent Bercot <ska@appnovation.com>
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/execline.html | 99 | ||||
| -rw-r--r-- | doc/index.html | 8 | ||||
| -rw-r--r-- | doc/upgrade.html | 3 |
3 files changed, 109 insertions, 1 deletions
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 @@ +<html> + <head> + <meta name="viewport" content="width=device-width, initial-scale=1.0" /> + <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> + <meta http-equiv="Content-Language" content="en" /> + <title>execline: the execline program</title> + <meta name="Description" content="execline: the execline program" /> + <meta name="Keywords" content="execline command multicall" /> + <!-- <link rel="stylesheet" type="text/css" href="//skarnet.org/default.css" /> --> + </head> +<body> + +<p> +<a href="index.html">execline</a><br /> +<a href="//skarnet.org/software/">Software</a><br /> +<a href="//skarnet.org/">skarnet.org</a> +</p> + +<h1> The <tt>execline</tt> program </h1> + +<p> +The <tt>execline</tt> program is only available when the +<tt>--enable-multicall</tt> option has been given to the <tt>configure</tt> +program at build time. In this configuration, <tt>execline</tt> is +a multicall binary implementing the functionality of <em>all</em> +the programs in the execline package; and the other programs, instead +of being executables of their own, are symbolic links to the +execline binary. +</p> + +<h2> Interface </h2> + +<pre> + execline <em>subcommand</em> <em>subcommand_arguments...</em> +</pre> + +<p> + execline will run the <em>subcommand</em> will its arguments. For +instance, <tt>execline cd / ls</tt> will run the equivalent of the +<a href="cd.html">program</a>, so this command will list the contents +of the <tt>/</tt> directory. +</p> + +<p> + Alternatively, if execline is called with the name of an existing +command, it will run the equivalent of that command. For instance, +if the <tt>/usr/bin/cd</tt> file is a (hard or symbolic) link to +the <tt>execline</tt> binary, <tt>/usr/bin/cd / ls</tt> will list +the contents of the <tt>/</tt> directory. +</p> + +<h2> Notes on the multicall configuration </h2> + +<p> + The <tt>--enable-multicall</tt> 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 <tt>--enable-multicall</tt> or not. +That means: any execline script should work the exact same way. +</p> + +<p> + 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. +</p> + +<p> + I am not a fan of multicall binaries at all. +</p> + +<p> + 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 <strong>huge</strong> 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. +</p> + +<p> + 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. +</p> + +</body> +</html> 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. </li> <ul> <li> See the enclosed INSTALL file for installation details. </li> + <li> Starting with 2.9.2.0, there's an <tt>--enable-multicall</tt> +configure option to save disk space. </li> </ul> <h3> Upgrade notes </h3> @@ -197,6 +199,12 @@ the previous versions of execline and the current one. </li> <li><a href="eltest.html">The <tt>eltest</tt> program</a></li> <li><a href="homeof.html">The <tt>homeof</tt> program</a></li> </ul> +<p> + (Multicall configuration) +</p> +<ul> +<li><a href="execline.html">The <tt>execline</tt> program</a></li> +</ul> <h3> Provided scripts: example <tt>.profile</tt> replacement </h3> diff --git a/doc/upgrade.html b/doc/upgrade.html index 21edcfc..735b6b6 100644 --- a/doc/upgrade.html +++ b/doc/upgrade.html @@ -23,7 +23,8 @@ <ul> <li> <a href="//skarnet.org/software/skalibs/">skalibs</a> dependency bumped to 2.13.1.0. </li> - <li> New experimental multicall feature. </li> + <li> New experimental multicall feature, with a new +<a href="execline.html">execline</a> binary. </li> </ul> <h2> in 2.9.1.0 </h2> |