How are dependencies specified for link steps with batchcmds?

[davidchisnall]

Several of the examples have something like this:

        batchcmds:add_depfiles(sourcefile_lex)
        batchcmds:set_depmtime(os.mtime(objectfile))
        batchcmds:set_depcache(target:dependfile(objectfile))

None of these have documentation, even in the form of useful code comments in the implementation. My guess as to the meanings is:

• add_depfiles adds one or more files to a set that will cause this set of batchcmds to be re-run if any of them have changed since the date set with set_depmtime
• set_depmtime sets the time that the files added with add_depfiles should be compared against.
• set_depcache does something, but I have no idea what.

For some reason, add_depfile must be called after the runv or whatever that actually does the job (this surprised me). It makes sense that set_depmtime would need to be called afterwards, but I am a bit confused by the fact that it's being passed os.mtime, rather than an object file to check, because the call to os.mtime happens during script evaluation and not when the buildcmds jobs actually run, so I don't see how this doesn't force a rebuild if the input files are modified after the script checks the modification time of the job.

I have two rules with custom link steps that are trying to use this mechanism. One of them runs only if one of the source files is modified, the other runs unconditionally.

[waruqi]

add_depfiles adds one or more files to a set that will cause this set of batchcmds to be re-run if any of them have changed since the date set with set_depmtime
set_depmtime sets the time that the files added with add_depfiles should be compared against.

right

set_depcache does something, but I have no idea what.

set the depend file *.d path, it will use a tmpfile if we did not set it.

For some reason, add_depfile must be called after the runv or whatever that actually does the job (this surprised me).

batchcmds:runv(), batchcmds:mkdir() and batchcmds:cp() are just generate a command list, they will be called at the right time, but not now.

Only the os.runv/os.cp command will be executed immediately

[davidchisnall]

set the depend file *.d path, it will use a tmpfile if we did not set it.

If my build command does not produce a .d file, is it fine to omit this? Will it default to assuming things that are are added with add_depfiles are the only things on which my command depends?

batchcmds:runv(), batchcmds:mkdir() and batchcmds:cp() are just generate a command list, they will be called at the right time, but not now.

So why does batchcmds:set_depmtime(os.mtime(objectfile)) work? Doesn't this read the modification time of the file now and then update it in the build system after the new target is updated with a build output that then appears newer than the modification time that we recorded? Or is this just relying on the fact that this happens in the on_load step, which is guaranteed to happen before any compile steps and so no intermediate targets should be updated in between?

I'm also slightly curious why I need to call this explicitly because every use I have is doing batchcmds:set_depmtime(targetos.mtime(target:targetfile())), which I'd assume to be the default (the target is up to date if the output file is built).

Tangentially related: it appears that there is an implicit assumption in xmake that a target produces a single output (except for object targets, which produce one output per input?). Is this actually an assumption, or did I miss something?

[waruqi]

If my build command does not produce a .d file, is it fine to omit this? Will it default to assuming things that are are added with add_depfiles are the only things on which my command depends?

right, it will generate one automatically.

So why does batchcmds:set_depmtime(os.mtime(objectfile)) work? Doesn't this read the modification time of the file now and then update it in the build system after the new target is updated with a build output that then appears newer than the modification time that we recorded? Or is this just relying on the fact that this happens in the on_load step, which is guaranteed to happen before any compile steps and so no intermediate targets should be updated in between?

It gets the mtime of the previously generated objectfile file, and the first time the objectfile is run, os.mtime returns 0 if it does not already exist, which also triggers batchcmds to be executed.

I'm also slightly curious why I need to call this explicitly because every use I have is doing batchcmds:set_depmtime(targetos.mtime(target:targetfile())), which I'd assume to be the default (the target is up to date if the output file is built).

batchcmds:set_depmtime is also optional, the default is to calculate mtime(dependfile(.d)) which is the .d file corresponding to the targetfile.