docs: document application command-chain by zyga · Pull Request #5599 · canonical/snapcraft

zyga · 2025-07-03T18:49:01Z

Have you followed the guidelines for contributing?
Have you signed the CLA?
Have you successfully run make lint?
Have you successfully run make test?

^ No, because those do not seem to work on my Fedora 42 system.

docs/explanation/command-chain.rst

agherzan · 2025-07-04T07:33:43Z

This looks good to me. The protocol explanation is a gem.

mr-cal · 2025-07-07T13:49:38Z

We will need to land #5603 first to fix the docs.

mr-cal · 2025-07-07T18:14:15Z

docs/explanation/command-chain.rst

+steps or anything else that makes sense in a given situation. Command chain
+elements are usually reusable across applications. Command chain elements are


Command chain elements are usually reusable across applications.

As in different app entries in the same snap or different snaps? The "usually" in this sentence and the next sentence are throwing me off. Is this referring to scripts that get re-used like desktop-launch or alsa-launch?

I tried to convey that you can use the same command chain element across many snaps and many apps as they are kind of "middleware". Let me know how to re-phrase that in the text.

Signed-off-by: Zygmunt Krynicki <me@zygoon.pl>

medubelko · 2025-07-24T20:27:02Z

docs/explanation/command-chain.rst

+Command chain is a mechanism for running small pieces of code before the main
+application executable. The chain uses ``exec`` to transition the process from
+the current element of the chain to the next. The last element of the chain is
+always the application executable.


Suggested change

Command chain is a mechanism for running small pieces of code before the main

application executable. The chain uses ``exec`` to transition the process from

the current element of the chain to the next. The last element of the chain is

always the application executable.

A command chain is a mechanism for running small pieces of code before the main

application executable. The chain uses ``exec`` to transition the process from

the current element of the chain to the next. The last element of the chain is

always the application executable.

It's important to use articles to distinguish between a concept/category, and actual objects in the software that users interact with.

medubelko · 2025-07-24T20:32:15Z

docs/explanation/command-chain.rst

+application executable. The chain uses ``exec`` to transition the process from
+the current element of the chain to the next. The last element of the chain is


What do you think of:

Suggested change

application executable. The chain uses ``exec`` to transition the process from

the current element of the chain to the next. The last element of the chain is

application executable. The chain uses the ``exec`` command to shift from

the current command to the next. The last element of the chain is

medubelko · 2025-07-24T20:51:53Z

docs/explanation/command-chain.rst

+Command chain may be used to modify process environment, perform initialization
+steps or anything else that makes sense in a given situation. Command chain
+elements are usually reusable across applications. Command chain elements are
+also usually stackable, so an application can use several tailored command
+chain elements to perform unrelated functions.


I tried to clear it up a little:

Suggested change

Command chain may be used to modify process environment, perform initialization

steps or anything else that makes sense in a given situation. Command chain

elements are usually reusable across applications. Command chain elements are

also usually stackable, so an application can use several tailored command

chain elements to perform unrelated functions.

A command chains is used to modify the process environment, perform initialization

steps, or any other situation where an ordered sequence of commands is needed.

Chained commands are usually reusable between apps in a part. The commands are

also usually stackable, so an application can use several tailored commands to

perform unrelated functions.

I said "apps in a part", but that might be too narrow for what @zyga is saying.

I'm not sure what we mean by "usually stackable". When are they not stackable? Isn't that an inherent quality of the concept?

The are stackable in the sense that you can take a command chain that, say, handles fontconfig cache, then another one that prepares your XDG configuration, then another one to generate locale data based on what the user is doing and each of those programs is entirely unrelated to each other, and can be used across apps and snaps.

I don't think I follow the metaphor. Is it different than being modular?

medubelko · 2025-07-24T20:55:27Z

docs/explanation/command-chain.rst

+       - bin/foo
+       - bin/bar


Suggested change

- bin/foo

- bin/bar

- bin/foo

- bin/bar

Not every system in our tooling plays nice with same-indentation collections.

medubelko · 2025-07-24T20:57:58Z

docs/explanation/command-chain.rst

+-------
+
+Both ``bin/foo`` and ``bin/bar`` can be written as simple shell scripts or
+comprehensive, compiled programs. A shell version might look like this.  Notice


Suggested change

comprehensive, compiled programs. A shell version might look like this. Notice

compiled programs. A shell version might look like this. Notice

medubelko · 2025-07-24T20:58:56Z

docs/explanation/command-chain.rst

+-------
+
+Both ``bin/foo`` and ``bin/bar`` can be written as simple shell scripts or
+comprehensive, compiled programs. A shell version might look like this.  Notice


I think I would put the "Notice..." sentence after the code block, so the reader has the chance to look at the code and think about it before we isolate part of it.

medubelko · 2025-07-24T21:01:41Z

docs/explanation/command-chain.rst

+calling ``exec`` (without forking the process).  Here both ``bin/foo`` and
+``bin/bar`` would follow the same protocol, ultimately executing ``bin/hello``.
+The next element of the chain is passed through the process argument vector.
+
+In the example above, ``snap-exec`` would call ``exec bin/foo bin/bar
+bin/hello`` with ``bin/foo`` as the program path and program name and ``bin/bar
+bin/hello`` as arguments. This protocol continues until the application entry
+point is reached.


Food for thought: this could also be visualised as a series of nodes in ASCII. It would reinforce the meaning.

medubelko · 2025-07-24T21:01:54Z

docs/explanation/command-chain.rst

+--------
+
+Every element of the chain is responsible for executing the next chain by
+calling ``exec`` (without forking the process).  Here both ``bin/foo`` and


Suggested change

calling ``exec`` (without forking the process). Here both ``bin/foo`` and

calling ``exec`` (without forking the process). Continuing with the previous example, both ``bin/foo`` and

zyga force-pushed the feature/command-chain-docs branch 4 times, most recently from 2e96ff5 to 5ef96ea Compare July 3, 2025 19:11

simondeziel reviewed Jul 3, 2025

View reviewed changes

docs/explanation/command-chain.rst Outdated Show resolved Hide resolved

zyga marked this pull request as ready for review July 4, 2025 06:37

zyga requested review from jahn-junior, medubelko and mr-cal as code owners July 4, 2025 06:37

mr-cal reviewed Jul 7, 2025

View reviewed changes

zyga force-pushed the feature/command-chain-docs branch from 758e827 to 30d78fe Compare July 21, 2025 10:33

docs: document application command-chain

6af3172

Signed-off-by: Zygmunt Krynicki <me@zygoon.pl>

zyga force-pushed the feature/command-chain-docs branch from 30d78fe to 6af3172 Compare July 21, 2025 10:35

zyga requested review from mr-cal and simondeziel July 21, 2025 10:35

simondeziel approved these changes Jul 21, 2025

View reviewed changes

medubelko reviewed Jul 24, 2025

View reviewed changes

		steps or anything else that makes sense in a given situation. Command chain
		elements are usually reusable across applications. Command chain elements are

		application executable. The chain uses ``exec`` to transition the process from
		the current element of the chain to the next. The last element of the chain is

-       - bin/foo
-       - bin/bar
+         - bin/foo
+         - bin/bar

	comprehensive, compiled programs. A shell version might look like this. Notice
	compiled programs. A shell version might look like this. Notice

	calling ``exec`` (without forking the process). Here both ``bin/foo`` and
	calling ``exec`` (without forking the process). Continuing with the previous example, both ``bin/foo`` and

Conversation

zyga commented Jul 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

agherzan commented Jul 4, 2025

Uh oh!

mr-cal commented Jul 7, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

zyga commented Jul 3, 2025 •

edited

Loading