ldepend - report a dep from a open-lmake job
ldepend [OPTION]... [FILE]...
ldepend may be used to pass flags to open-lmake.
Each dep is associated with an access pattern. Accesses are of 3 kinds, regular, link and stat:
|
• |
Regular means that the file was accessed using open(2) or similar, i.e. the job is sensitive to the file content if it is a regular file, but not to the target in case it is a symbolic link. | ||
|
• |
Link means that the file was accessed using readlink(2) or similar, i.e. the job is sensitive to the target if it is a symbolic link, but not to the content in case it is a regular file. | ||
|
• |
Stat means that the file meta-data were accessed, i.e. the job is sensitive to file existence and type, but not to the content or its target. |
If a file have none of these accesses, changing it will not trigger a rebuild, but it is still a dep as in case it is in error, this will prevent the job from being run. Making such dinstinctions is most useful for the automatic processing of symbolic links. For example, if file a/b is opened for reading, and it turns out to be a symbolic link to c, open-lmake will set a dep to a/b as a link, and to a/c as a link (in case it is itself a link) and regular (as it is opened).
By default, passed deps are associated with no access, but are required to be buildable and produced without error. To simulate a plain access, you need to pass the --read option to associate accesses and the --no-required to allow it not to exist.
Note that :
|
• |
Generated deps are parallel, i.e. a modification on a dep will not mask an error on another one (cf. note (3)). | ||
|
• |
Deps are acquired all at once (cf. note (4)). | ||
|
• |
Flags can be passed in (cf. OPTIONS below). Flags accumulate and will apply even if the file is independently accessed. | ||
|
• |
Deps are reported even if the autodep method (the autodep rule attribute) is none. This is the way (or a call to lmake.depend) of reporting deps in such a case (usually with --read). |
-L, --follow-symlinks
Follow the last level symbolic link, default is not to follow.
-d, --direct
Build deps before command completion (cf. note (5)).
-v, --verbose
Write lines composed of:
|
status |
ok if dep is built ok, error if dep is built in error, ??? if dep is no built. |
checksum
See xxhsum(1).
|
rule |
The rule name of the job that has generated the dep. |
|||
|
file |
The file name |
For each file, such line is followed by one line for each stem, starting with a tab, composed of the name of the stem followed by its value.
-R, --read
Report an actual read. Default is to only alter flags.
-z, --dir
Specify a directory for use with --list.
-l, --list
Print list of currently accessed deps to stdout. Only deps lying in the dir mentioned with --dir are listed (if this option is used), and only if they match the regexpr argument (if --regexpr) as reported. If the cwd lies outside the repo, listed files are absolute, else they are relative unless they are within an absolute source dir. The order of the listed deps is the chronological order. Cf note (6).
-c, --critical
Create critical deps (cf. note (7)).
-D, --readdir-ok
Allow readdir(3) on passed deps even if not ignored nor incremental. Implies flag --no-required.
-E, --essential
Passed deps will appear in the flow shown with a graphical tool.
-e, --ignore-error
Ignore the error status of the passed deps.
-r, --no-required
Accept that deps be not buildable, as for a normal read access (in such a case, the read may fail, but open-lmake is ok).
-x, --no-exclude-star
Accept that flags are further processed according to regexpr-based requests, default is to exclude such processing.
-I, --ignore
From now on, ignore all reads of deps (including readdir(3)).
-X, --regexpr
Pass flags to all deps matching regexprs passed as argument. The ignore flag only applies to targets following this command. Default is to optimize dep check as much as possible.
ldepend --ignore a_file
ldepend --read a b
cat a_file
ldepend --readir_ok --regexpr a_dir(/.*)?’’
find a_dir
|
(1) |
The same functionality is provided with the lmake.depend python function. | ||
|
(2) |
Flags can be associated to deps on a regexpr (matching on dep name) basis by using the side_deps rule attribute. | ||
|
(3) |
If cat a b is executed, open-lmake sees 2 open(2) system calls, to a then to b, exactly the same sequence that if one did cat $(cat a) and a contained b. |
Suppose now that b is an error. This is a reason for your job to be in error. But if a is modified, in the former case, this cannot solve your error while in the latter case, it may if the new content of a points to a file that may successfully be built. Because open-lmake cannot distinguish between the 2 cases, upon a modification of a, the job will be rerun in the hope that b is not accessed any more. Parallel deps prevents this trial.
|
(4) |
If a series of files are read in a loop and the loop is written in such a way as to stop on the first error and if the series of file does not depend on the actual content of said files, then it is preferable to pre-access (using ldepend) all files before starting the loop. The reason is that without this precaution, deps will be discovered one by one and may be built serially instead of all of them in parallel. | ||
|
(5) |
Using direct deps is not recommanded for general use as it suffers 2 drawbacks: |
- successive calls leads to
serial jobs (as each job is analyzed once the previous has
completed)
- this may generate dead-lock if the calling job holds
resources (which is usually the case) as such resources are
kept while the job is waiting
This flag is meant in exceptional situations such as a
dichotomy search in which a dep is necessary at each step of
the dichotomy. In that case, using the direct flag
reduces the number of reruns, which can occur for each step
otherwise. In that case, it is most probably wise to use the
critical flag simultaneously.
|
(6) |
--list is provided as a secure way to replace readdir(3). Using this feature only relies on job execution, not spurious files that can exist without the possibility of depending on such list. | ||
|
(7) |
If a series of dep is directly derived from the content of a file, it may be wise to declare it as critical. When a critical dep is modified, open-lmake forgets about deps reported after it. |
Usually, when a file is modified, this has no influence on the list of files that are accessed after it, and open-lmake anticipates this by building these deps speculatively. But in some situations, it is almost certain that there will be an influence and it is preferable not to anticipate. this is what critical deps are made for: in case of modifications, following deps are not built speculatively.
lautodep(1), lcheck_deps(1), lcollect(1), ldebug(1), ldecode(1), ldircache_repair(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/.