man: Section-1 man page for just-mr

Co-authored-by: Oliver Reiche <oliver.reiche@huawei.com>

1 files changed, 168 insertions, 0 deletions

diff --git a/share/man/just-mr.1.org b/share/man/just-mr.1.org
new file mode 100644
index 00000000..a3a9b57c
--- /dev/null
+++ b/share/man/just-mr.1.org
@@ -0,0 +1,168 @@
+#+TITLE: JUST-MR
+#+MAN_CLASS_OPTIONS: section-id=1
+
+* NAME
+
+just-mr - multi-repository configuration tool and launcher for *just(1)*.
+
+* SYNOPSIS
+
+just-mr [OPTIONS] {setup|setup-env} [--all] [main-repo]\\
+just-mr [OPTIONS] fetch [--all] [-o fetch-dir] [main-repo]\\
+just-mr [OPTIONS] update [repo...]\\
+just-mr [OPTIONS] do [JUST ARGS]\\
+just-mr [OPTIONS] {version|analyse|build|install|install-cas|describe|rebuild} [JUST ARGS]\\
+
+* DESCRIPTION
+
+Just-MR is a configuration tool for the multi-repository Just build system. It
+can be used both standalone and as a launcher for ~just~.
+
+The tool performs specific operations, based on the invoked subcommand, on
+repositories described in a configuration file. All subcommands operate at the
+level of /workspace roots/ deduced from the given repository descriptions.
+See *just-mr-repository-config(5)* for more details on the input format.
+
+* OPTIONS
+
+** General options
+
+   *-h*, *--help*
+   Output a usage message and exit.\\
+
+   *-C*, *--repository-config* PATH\\
+   Path to the multi-repository configuration file. See
+   *just-mr-repository-config(5)* for more details. If no configuration file is
+   *specified, ~just-mr~ will look for one in the following order:\\
+    - ~$WORKSPACE_ROOT/repos.json~ (workspace of the ~just-mr~ invocation)
+    - ~$WORKSPACE_ROOT/etc/repos.json~ (workspace of the ~just-mr~ invocation)
+    - ~$HOME/.just-repos.json~
+    - ~/etc/just-repos.json~
+   The default configuration lookup order can be adjusted in the just-mrrc file.
+   See *just-mrrc(5)* for more details.
+
+   *--local-build-root* PATH\\
+   Root for local CAS, cache, and build directories. The path will be
+   created if it does not exist already. This option overwrites any values set
+   in the *just-mrrc(5)* file.\\
+   Default: path ~".cache/just"~ in user's home directory.
+
+   *-L*, *--checkout-locations* PATH\\
+   Specification file for checkout locations. This file contains a JSON object,
+   for which under the key ~"<version control>"~ of key ~"checkouts"~ we get
+   pairs of repository URLs as keys and absolute paths as values. Currently
+   supported version control is Git, therefore the respective key is ~"git"~.
+   The paths contained for each repository URL point to existing locations on
+   the filesystem containing the checkout of the respective repository. This
+   options overwrites any values set in the *just-mrrc(5)* file.\\
+   Default: file path ~".just-local.json"~ in user's home directory.
+
+   *--distdir* PATH\\
+   Directory to look for distfiles before fetching. If given, this will be the
+   first place distfiles are looked for. This option can be given multiple times
+   to specify a list of distribution directories that are used for lookup in the
+   order they appear on the command line. Directories specified via this option
+   will be appended to the ones set in the *just-mrrc(5)* file.\\
+   Default: the single file path ~".distfiles"~ in user's home directory.
+
+   *--main* NAME\\
+   The repository to take the target from.\\
+
+   *--just* PATH\\
+   Path to the just binary. Default: ~"just"~.\\
+
+   *--rc* PATH\\
+   Path to the just-mrrc file to use. See *just-mrrc(5)* for more details.\\
+   Default: file path ~".just-mrrc"~ in the user's home directory.
+
+   *--norc*\\
+   Option to prevent reading any *just-mrrc(5)* file.
+
+* SUBCOMMANDS
+
+** setup|setup-env
+
+These subcommands fetch all required repositories and generate an appropriate
+multi-repository ~just~ configuration file. The resulting file is stored in CAS
+and its path is printed to stdout. See *just-repository-config(5)* for more
+details on the resulting configuration file format.
+
+If a main repository is provided in the input configuration or on command line,
+only it and its dependencies are considered in the generation of the resulting
+multi-repository configuration file. If no main repository is provided, the
+lexicographical first repository from the configuration is used. To perform the
+setup for all repositories from the input configuration file, use the ~--all~
+flag.
+
+The behavior of the two subcommands differs only with respect to the main
+repository. In the case of ~setup-env~, the workspace root of the main
+repository is left out, such that it can be deduced from the working directory
+when ~just~ is invoked. In this way, working on a checkout of that repository is
+possible, while having all of its dependencies properly set up. In the case of
+~setup~, the workspace root of the main repository is taken as-is into the
+output configuration file.
+
+** fetch
+
+This subcommand prepares all archive-type workspace roots for an offline build
+by fetching all their required source files from the specified locations
+given in the input configuration file. Any subsequent ~just-mr~ or ~just~
+invocations containing fetched archive workspace roots will thus need no further
+network connections.
+
+If a main repository is provided in the input configuration or on command line,
+only it and its dependencies are considered for fetching. If no main repository
+is provided, the lexicographical first repository from the configuration is
+used. To perform the fetch for all repositories from the input configuration
+file, use the ~--all~ flag.
+
+By default the first existing distribution directory is used as the output
+directory for writing the fetched archives on disk. If no existing distribution
+directory can be found an error is produced. To define an output directory that
+is independent of the given distribution directories, use the ~-o~ option.
+
+** update
+
+This subcommand updates the specified repositories (possibly none) and prints
+the resulting updated configuration file to stdout.
+
+Currently, ~just-mr~ can only update Git repositories and it will fail if a
+different repository type is given. The tool also fails if any of the given
+repository names are not found in the configuration file.
+
+For Git repositories, the subcommand will replace the value for the ~"commit"~
+field with the commit hash (as a string) found in the remote repository in the
+specified branch. The output configuration file will otherwise remain the same
+at the JSON level with the input configuration file.
+
+** do
+
+This subcommand is used as the canonical way of specifying just arguments and
+calling ~just~ via *execvp(2)*. Any subsequent argument is unconditionally
+forwarded to ~just~. For /known/ subcommands (version, describe, analyse, build,
+install, install-cas, rebuild), the ~just-mr setup~ step is performed first for
+those commands accepting a configuration and the produced configuration is
+prefixed to the provided arguments. The main repository for the ~setup~ step can
+be provided in the configuration or on the command line. If no main repository
+is provided, the lexicographical first repository from the configuration is
+used.
+
+** version|describe|analyse|build|install|install-cas|rebuild
+
+This subcommand is the explicit way of specifying /known/ just subcommands and
+calling ~just~ via *execvp(2)*. The same description as for the ~do~ subcommand
+applies.
+
+* EXIT STATUS
+
+The exit status of ~just-mr~ is one of the following values:
+  - 0: the command completed successfully
+  - 64: setup succeeded, but exec failed
+  - 65: any other error occurred in just-mr
+
+Any other exit code that does not have bit 64 set is a status value from ~just~,
+if ~just-mr~ is used as a launcher. See *just(1)* for more details.
+
+* See also
+
+*just(1)*