ldebug - run a job in a debug environment
ldebug [OPTION]... [FILE]...
ldebug generates a script that precisely mimics the job execution under lmake(1) control, and runs it.
Once the script is generated, its path is printed. It can then be freely modified and executed without needing to run ldebug again.
The job must have been run with lmake before (but may not have finished, it just needs to have started) because a lot of information is generated at that time. The precise way the job is launched is controled by the configuration lmake.config.debug[<key>] which provides the name of a module to import. This module must contain a (gen_script) function taking a description of the job provided as keyword arguments and returning the script to execute. Several such scripts exist in lib/lmake_debug in the installation dir and can serv as examples to start with.
When ldebug is run, the debug script is generated in a file within the LMAKE dir and, unless --no-exec, it is executed.
ldebug 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 ldebug 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.
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.
These options
are specific to ldebug :
-k key, --key=key
Use key to find the function generating the debug script. Default is ’’ (the empty string), which looks by default (unless overridden in Lmakefile.py) in the lmake_debug/default.py module.
-n, --no-exec
Dont run the debug script, stop after generation.
-t, --std-tmp
By default the tmp dir used during job execution is the one provided by the $TMPDIR variable for the job if there is one. If its value is ... (python ellipsis), the value provided by the local backend (and not the backend for the job as debug execution is local) is use. If this does not lead to a value, the standard value is used : LMAKE/debug/<job_id>/tmp. When this option is used, the tmp dir is forced to its standard value, regardless of job and backend environment.
-T abs_dir, --tmp-dir=abs_dir
When this option is used, it forces the tmp dir for job execution to its value.
Unless overridden in the configuration (through the dict lmake.config.debug), the following standard debug methods are provided :
|
(1) |
Running with the -x flag usually produces a trace of executed commands. | ||
|
(2) |
Alias r is redefined to run with adequate redirections. | ||
|
(3) |
Providing a working pudb with redirected stdin/stdout necessitated to patch it. This patch is dynamically applied as part of the job start up procedure. | ||
|
(4) |
An interactive shell (as provided by $SHELL, which defaults to /bin/bash) is open in the job environment (environment, cwd, namespace, chroot, mounts, tmp, ...). |
$HOME and $SHLVL are kept from actual environment to ease interactive session. In particular $SHLVL can be used to provide a differentiated prompt if adequately defined in the start up file (usually ˜/.bashrc).
In addition to
running the job, these standard modules provide the
following environment variables to the job :
$LMAKE_DEBUG_KEY
The key provided by the -k or --key option.
$LMAKE_DEBUG_STDIN
The file connected as stdin to ldebug when it was launched (usually a tty) if the job has its stdin redirected (in case the dep rule attribute is defined).
$LMAKE_DEBUG_STDOUT
The file connected as stdout to ldebug when it was launched (usually a tty) if the job has its stdout redirected (in case the target rule attribute is defined).
Debug script files are generated in the LMAKE/debug dir as LMAKE/debug/<job id>/script. Associated files are besides the the script files.
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, ldebug will not start.
lib/lmake_debug/*.py files in the installation dir are used by default to generate debug scripts.
˜/.bashrc is usually executed when entering in the job environment.
lautodep(1), lcheck_deps(1), ldecode(1), ldepend(1), lencode(1), lforget(1), lmake(1), lmark(1), lrepair(1), lrun_cc(1), lshow(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/.