lshow - show various information about jobs in the open-lmake build system
lshow [OPTION]... [FILE]...
Unless the --job option is given, arguments are files and information are provided about the official jobs generating these as targets, if any. Else, information about the job that actually produced the job (a.k.a the polluting job) are provided.
lshow manages a fully coherent dir called a repo. When it starts, it first determines the root of the repo (cf. FILES below).
Arguments and reports are systematically localized to the current working dir. For example, if you launch lshow b from dir a in your repo, the argument is file a/b from the root of the repo and reports containing file names (initially seen from the root of the repo) will be shown relative the the current working dir.
If launched from a terminal, output is colored. Colors are different depending on whether terminal is normal (black on white) or reverse (white on black) video. These colors can be configured. The colors bears a semantic:
|
• |
Green means success. | ||
|
• |
Orange means possible error, depending on future (if error is confirmed, it will be repeated in red). | ||
|
• |
Red means error. | ||
|
• |
Magenta means warning. | ||
|
• |
Blue means notes. | ||
|
• |
Gray means information of secondary importance. | ||
|
• |
Uncolored means general output. In some occasion, it may be colored by user code (e.g. gcc generates colored error messages). |
If $LMAKE_VIDEO is defined, it is processed as if provided to the --video option.
These options
are common to all tools of the open-lmake set of
utilities :
--version
Print version and exit. Version is in the form "year.month.tag (key)" where "year.month" forms the major version, "tag" the minor version and "key" is indicates the format of the persistent information.
-h, --help
Print a short help and exit. It is composed of:
|
• |
The command line synoptic. | ||
|
• |
Version as described above. | ||
|
• |
A line for each supported option with its short name, long name, whether it has an argument and a short explanation. |
-J, --job
Passed arguments are interpreted as job names rather than as file names. Job names are the names that appear, for example, on start and done lines when lmake executes a job.
-R rule, --rule=rule
When the --job option is used, this options allows the specification of a rule, given by its name. This is necessary when the job name is ambiguous as several rules may lead to the same job name.
-q, --quiet
Do not generate user oriented messages. Strictly generate what is asked. This is practical if output is meant for automatic processing.
-S, --sync
Ensure server is launched (i.e. do not connect to an existing server) and wait for its termination. This is exceptionally useful in scripts that modify Lmakefile.py.
-v, --verbose
Generate more prolix output.
-V mode, --video=mode
Explicitly ask for a video mode instead of interrogating connected terminal. If mode starts with n or N, normal video (black on white) is assumed. If it starts with r or R, reverse video (white on black) is assumed. Else output is not colorized. video mode has an impact on generated colors as nice looking colors are not the same in each case.
A single
sub-command must be provided :
-b, --bom
Output the list of all source files necessary to build the arguments. If --verbose option is provided, intermediate files are shown in gray.
If --porcelaine, the output is generated as set (if not --verbose) or as a tuple (if --verbose). In the latter case, it is guaranteed that deps are going downards, i.e. dependents appear before their deps. If arguments are files, the output is not a dict and is the list necessary to generate all the arguments.
-c, --cmd
Output the cmd used to execute the job. If dynamic, it shows it as specialized for this job. Output is always generated with a single tab prefix for each line, so as to maintain internal alignment.
If --porcelaine, the output is generated as a str (not indented).
-d, --deps
Output the list of all the deps of the jobs. Unless --verbose, only existing deps are shown.
If --quiet, the raw list of deps is output, with no header nor decoration.
Unless --quiet, each line is composed of 5 fields separated by spaces :
|
• |
Flags : each flag is either a letter if set, or a - if not : |
E
|
dep is essential, i.e. dep is show in a future graphical tool. | |||
|
c |
dep is critical | ||
|
e |
ignore errors on dep, i.e. job can be run even if this dep is built in error. | ||
|
r |
dep is required, i.e. job is in error if dep is not buildable. For static deps, job is not even tried if dep is not buildable (and another rule is used if possible). | ||
|
S |
dep is static. | ||
|
• |
Accesses : each kind of accesses is either a letter if done, or a - if not :
|
L |
dep has been accessed as a symbolic link. | ||
|
R |
dep has been accessed as a regular file. | ||
|
T |
dep has been accessed with a stat-like system call (i.e. its inode has been accessed). | ||
|
• |
Key : the key if the dep is static, else blank.
|
• |
Ascii art showing parallel deps (deps coming from a single call to ldepend(1) or lmake.depend are considered parallel). | ||
|
• |
lshow of the dep. |
If a dep does not exist, it is deemed secondary information and is shown in gray.
If --porcelaine and args are files, the output is, for each file, a dict indexed by jobs and whose values are as follows. Jobs are represented as a tuple composed of the rule name, the job name and a comment. The keys are all jobs potentially producing given file. If arg is a job, the output is a mentioned below.
The value is a tuple of sequential deps groups, each deps group being a set of parallel deps. Each dep is represented as a tuple composed of dep flags, access flags, key and name.
-D, --inv-deps
Show jobs that depend on args. This sub-command is only valid for file args.
If --verbose, obsolete jobs are also listed in gray.
If --porcelaine, the output is a set of jobs, each job being represented as a tuple composed of the rule name and the job name.
-E, --env
Show the environment used to run the script
If --porcelaine, the output is generated as as dict, much like os.environ.
-i, --info
Show various info about a job, as it last ran (unless stated otherwise):
|
• |
rule : the rule name. | ||
|
• |
job : the job name. | ||
|
• |
ids : the job-id (unique for each job), the small-id (unique among jobs running simultaneously) and the seq-id (unique in a repo). | ||
|
• |
required by : the job that last necessitated job to run. | ||
|
• |
reason : the reason why job ran. | ||
|
• |
host : the host on which job ran. | ||
|
• |
scheduling : the ETA of the lmake command, a -, the duration from start-of-job to end-of-lmake command along the longest dep path as estimated at run time (known as the pressure). Jobs are scheduled by giving higher priority to nearer ETA, then to higher pressure. | ||
|
• |
chroot_dir : the chroot dir in which job ran. | ||
|
• |
lmake_view : the name under which the lmake installation dir was seen by job. | ||
|
• |
repo_view : the name under which the repo root dir was seen by job. | ||
|
• |
tmp_view : the name under which the tmp dir was seen by job. | ||
|
• |
sub_repo : the sub-repo in which rule was defined. | ||
|
• |
auto_mkdir : true if chdir(2) to a non-existent triggered an automatic mkdir(2) for the chdir(2) to succeed. | ||
|
• |
autodep : the autodep method used. | ||
|
• |
timeout : the timeout after which job would have/has been killed. | ||
|
• |
use_script : true if a script was used to launch job (rather than directly using the -c option to the interpreter). bullet backend : the backend used to launch job. | ||
|
• |
run status : whether job could be run last time the need arose (note: if not ok it is later than when job last ran). Possible values are: |
ok
|
job could run. |
dep_err
job could not run because a dep was in error.
missing_static
job could not run because a static dep was missing.
|
err |
job could not run because an error was detected before it started. | ||
|
• |
end date : the date at which job ended.
|
• |
status : job status, as used by open-lmake. Possible values are: |
new
|
job was never run |
early_chk_deps
dep check failed before job actually started
early_err
job was not started because of error
early_lost
job was lost before starting, retry
early_lost_err
job was lost before starting, do not retry
late_lost
job was lost after having started, retry
late_lost_err
job was lost after having started, do not retry
|
killed |
job was killed |
chk_deps
dep check failed
cache_match
cache just reported deps, not result
bad_target
target was not correctly initialized or simultaneously written by another job
|
ok |
job execution ended successfully |
submit_loop
job needs to rerun but was already submitted too many times
|
err |
job execution ended in error |
|||
|
• |
physical tmp dir : the tmp dir on disk when viewed by job under another name.
|
• |
tmp dir : the tmp dir on disk when viewed by job under the same name. | ||
|
• |
rc : the return code of the job. Possible values are: |
ok
|
exited with code 0 and stderr was empty or allowed to be non-empty. |
ok (with non-empty stderr)
exited with code 0 and stderr was non-empty nor allowed to be non-empty.
exit <n>
exited with code <n> (non-zero).
exit <n> (could be signal<s>)
exited with code <n> which is possibly generated by the shell in response to a process killed by signal <s>.
signal <s>
killed with signal <s>.
|
• |
cpu time : user+system cpu time of job, as reported by getrusage(2) with children. | ||
|
• |
elapsed in job : elapsed time in job, excluding overhead. | ||
|
• |
elapsed total : elapsed time in job, including overhead. bullet used mem : max RSS, as reported by getrusage(2) with children. | ||
|
• |
cost : elapsed time in job divided by the average number of jobs running in parallel. This value is used to compute the ETA of the lmake command. | ||
|
• |
total size : the sum of the sizes of all targets. | ||
|
• |
compressed size : the sum of the sizes of all targets after compression as stored in cache. | ||
|
• |
start message : a message emitted at job start time. | ||
|
• |
message : a message emitted at job end time. | ||
|
• |
views : the view map as specified in the views rule attribute. | ||
|
• |
resources : the job resources. In some cases, the atual allocated resources is different from the required resources, in which case both values are shown. |
All information are not necessarily shown:
|
• |
If the job is running, information that are only available after job end are not shown. | ||
|
• |
Non-pertinent information (e.g. compressed size when targets have not been compressed) are not shown. | ||
|
• |
0, false or other values carrying no information are not shown. |
If --porcelaine, the output contains the same information generated as a dict.
-r, --running
Show the list of jobs currently running to build the arguments. If --verbose, some waiting jobs are shown in gray, prefixed by key W, enough to justify why all running jobs are running. Queued jobs are shown in blue, prefixed with key Q, actively running jobs are uncolored, prefixed with key R.
If --porcelaine, whether args are a job or files, the output is a set (if not --verbose) or a tuple (if --verbose) of jobs. Each job is represented as a tuple composed of the key (W’’, Q’’ or R’’), the rule name and the job name.
-e, --stderr
Show the stderr of the jobs. Unless --quiet, output is preceded by a description of the job which it relates to. Output is always generated with a single tab prefix for each line, so as to maintain internal alignment.
If --porcelaine, the output is generated as a tuple composed of a message generated by lmake at start time, a message generated by lmake at en time and the stderr of the job. All three items are str (not indented).
-o, --stdout
Show the stdout of the jobs. Unless --quiet, output is preceded by a description of the job which it relates to.
If --porcelaine, the output is generated as a str.
-t, --targets
Show the targets of the jobs. Unless --verbose, only existing targets are shown.
If --quiet, the raw list of targets is output, with no header nor decoration.
Unless --quiet, each line is composed of 3 fields separated by spaces :
|
• |
Info : composed of 1 characters : W if target was written, U if target was unlinked, else -. | ||
|
• |
Flags : each flag is either a letter if set, or a - if not : |
E
|
target is essential, i.e. target is show in a future graphical tool. | |||
|
i |
target is incremental, i.e. it is not unlinked before job execution and read accesses are ignored | ||
|
p |
target is phony, i.e. being non existing a considered as a particular value for that file | ||
|
u |
target is not uniquified if several links point to it before job execution (only meaningful for incremental targets). | ||
|
w |
no warning is emitted if target is either uniquified or unlinked while produced by another job. | ||
|
S |
target is static. | ||
|
T |
target is official, i.e. job can be triggered when another one depend on this target. | ||
|
• |
The name of the target.
If a target does not exist, it is deemed secondary information and is shown in gray.
If --porcelaine, the output is generated as a set of targets, each target being represented as a tuple composed the info (W’’, U’’ or -’’), the target flags, the key and the target name.
-T, --inv-targets
Show jobs that have given file as a target (either official or not). This sub-command is only valid for file args.
If --verbose, obsolete jobs are also listed in gray.
If --porcelaine, the output is a set of jobs, each job being represented as a tuple composed of the rule name and the job name.
-u, --trace
Show an execution trace of the jobs. Each entry is compose of a date, a tag and a file (or other info, depending on tag). The tag is either a keyword, of a keyword with various attributes in (). Accesses generating no new dep are not shown.
The main purpose is to provide an explanation for each dep and target.
If --porcelaine, the output is generated as a tuple of entries, each entry being represented as a tuple composed of a date, a tag and a file (as described above), each being a str.
These options
are specific to lshow :
-p, --porcelaine
In porcelaine mode, information is provided as an easy-to-parse python object. Also,reported files are relative to the root of the repo, not the current workind dir.
If argument is a job, the output is as described for each sub-command. unless mentioned otherwise, if arguments are files, the output is a dict whose keys are the arguments and values are as described above.
The content of $LMAKE_VIDEO is processed as if provided with the --video option.
The files Lmakefile.py or Lmakefile/__init__.py are searched in the current dir and in parent dirs. If a single one is found, this determines the root of the repo. If several are found, the existence of an LMAKE dir is checked. If a single one is found, this determines the root of the repo. In other cases, lshow will not start.
lautodep(1), lcheck_deps(1), ldebug(1), ldecode(1), ldepend(1), lencode(1), lforget(1), lmake(1), lmark(1), lrepair(1), lrun_cc(1), ltarget(1), xxhsum(1)
The python module lmake.
The full open-lmake documentation in <open-lmake-installation-dir>/docs/index.html.
Copyright © 2023-2025, Doliam. This file is part of open-lmake.
open-lmake is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, version 3 of the License.
open-lmake is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.