From ffc8f5a6d801c346ef0c1cfcd5e155471aa54f77 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ludwig=20H=C3=A4hne?= Date: Fri, 22 Aug 2008 15:36:49 +0000 Subject: Issue 1984: Documentation for ParseDepends --- doc/scons.mod | 1 + doc/user/depends.in | 176 +++++++++++++++++++++++++++++++++++++++++++++++++++ doc/user/depends.xml | 142 ++++++++++++++++++++++++++++++++++++++++- 3 files changed, 318 insertions(+), 1 deletion(-) diff --git a/doc/scons.mod b/doc/scons.mod index deeee33..b924a24 100644 --- a/doc/scons.mod +++ b/doc/scons.mod @@ -214,6 +214,7 @@ PackageOption"> PackageVariable"> ParseConfig"> +ParseDepends"> ParseFlags"> PathOption"> PathOption.PathAccept"> diff --git a/doc/user/depends.in b/doc/user/depends.in index e861cbe..1309807 100644 --- a/doc/user/depends.in +++ b/doc/user/depends.in @@ -1267,6 +1267,182 @@
+ Dependencies From External Files: the &ParseDepends; + Function + + + + &SCons; has built-in scanners for a number of languages. Sometimes + these scanners fail to extract certain implicit dependencies due + to limitations of the scanner implementation. + + + + + + The following example illustrates a case where the built-in C + scanner is unable to extract the implicit dependency on a header + file. + + + + + + #define FOO_HEADER <foo.h> + #include FOO_HEADER + + int main() { + return FOO; + } + + + Program('hello', 'hello.c', CPPPATH='.') + + + #define FOO 42 + + + + + scons -Q + edit foo.h + scons -Q + + + + + Apparently, the scanner does not know about the header dependency. + Being not a full-fledged C preprocessor, the scanner does not + expand the macro. + + + + + + In these cases, you may also use the compiler to extract the + implicit dependencies. &ParseDepends; can parse the contents of + the compiler output in the style of &Make;, and explicitly + establish all of the listed dependencies. + + + + + + The following example uses &ParseDepends; to process a compiler + generated dependency file which is generated as a side effect + during compilation of the object file: + + + + + + + + #define FOO_HEADER <foo.h> + #include FOO_HEADER + + int main() { + return FOO; + } + + + obj = Object('hello.c', CCFLAGS='-MD -MF hello.d', CPPPATH='.') + SideEffect('hello.d', obj) + ParseDepends('hello.d') + Program('hello', obj) + + + #define FOO 42 + + + hello.o: hello.c foo.h + + + + + scons -Q + edit foo.h + scons -Q + + + + + Parsing dependencies from a compiler-generated + .d file has a chicken-and-egg problem, that + causes unnecessary rebuilds: + + + + + + #define FOO_HEADER <foo.h> + #include FOO_HEADER + + int main() { + return FOO; + } + + + obj = Object('hello.c', CCFLAGS='-MD -MF hello.d', CPPPATH='.') + SideEffect('hello.d', obj) + ParseDepends('hello.d') + Program('hello', obj) + + + #define FOO 42 + + + + + + + % scons -Q + cc -o hello.o -c -MD -MF hello.d -I. hello.c + cc -o hello hello.o + % scons -Q --debug=explain + scons: rebuilding `hello.o' because `foo.h' is a new dependency + cc -o hello.o -c -MD -MF hello.d -I. hello.c + % scons -Q + scons: `.' is up to date. + + + + + In the first pass, the dependency file is generated while the + object file is compiled. At that time, &SCons; does not know about + the dependency on foo.h. In the second pass, + the object file is regenerated because foo.h + is detected as a new dependency. + + + + + + &ParseDepends; immediately reads the specified file at invocation + time and just returns if the file does not exist. A dependency + file generated during the build process is not automatically + parsed again. Hence, the compiler-extracted dependencies are not + stored in the signature database during the same build pass. This + limitation of &ParseDepends; leads to unnecessary recompilations. + Therefore, &ParseDepends; should only be used if scanners are not + available for the employed language or not powerful enough for the + specific task. + + + +
+ +
Ignoring Dependencies: the &Ignore; Function diff --git a/doc/user/depends.xml b/doc/user/depends.xml index b19b4b2..61d2579 100644 --- a/doc/user/depends.xml +++ b/doc/user/depends.xml @@ -1270,6 +1270,146 @@
+ Dependencies From External Files: the &ParseDepends; + Function + + + + &SCons; has built-in scanners for a number of languages. Sometimes + these scanners fail to extract certain implicit dependencies due + to limitations of the scanner implementation. + + + + + + The following example illustrates a case where the built-in C + scanner is unable to extract the implicit dependency on a header + file. + + + + + #define FOO_HEADER <foo.h> + #include FOO_HEADER + + int main() { + return FOO; + } + + + + % scons -Q + cc -o hello.o -c -I. hello.c + cc -o hello hello.o + % edit foo.h + [CHANGE CONTENTS OF foo.h] + % scons -Q + scons: `.' is up to date. + + + + + Apparently, the scanner does not know about the header dependency. + Being not a full-fledged C preprocessor, the scanner does not + expand the macro. + + + + + + In these cases, you may also use the compiler to extract the + implicit dependencies. &ParseDepends; can parse the contents of + the compiler output in the style of &Make;, and explicitly + establish all of the listed dependencies. + + + + + + The following example uses &ParseDepends; to process a compiler + generated dependency file which is generated as a side effect + during compilation of the object file: + + + + + + + obj = Object('hello.c', CCFLAGS='-MD -MF hello.d', CPPPATH='.') + SideEffect('hello.d', obj) + ParseDepends('hello.d') + Program('hello', obj) + + + + % scons -Q + cc -o hello.o -c -MD -MF hello.d -I. hello.c + cc -o hello hello.o + % edit foo.h + [CHANGE CONTENTS OF foo.h] + % scons -Q + cc -o hello.o -c -MD -MF hello.d -I. hello.c + + + + + Parsing dependencies from a compiler-generated + .d file has a chicken-and-egg problem, that + causes unnecessary rebuilds: + + + + + + + + + % scons -Q + cc -o hello.o -c -MD -MF hello.d -I. hello.c + cc -o hello hello.o + % scons -Q --debug=explain + scons: rebuilding `hello.o' because `foo.h' is a new dependency + cc -o hello.o -c -MD -MF hello.d -I. hello.c + % scons -Q + scons: `.' is up to date. + + + + + In the first pass, the dependency file is generated while the + object file is compiled. At that time, &SCons; does not know about + the dependency on foo.h. In the second pass, + the object file is regenerated because foo.h + is detected as a new dependency. + + + + + + &ParseDepends; immediately reads the specified file at invocation + time and just returns if the file does not exist. A dependency + file generated during the build process is not automatically + parsed again. Hence, the compiler-extracted dependencies are not + stored in the signature database during the same build pass. This + limitation of &ParseDepends; leads to unnecessary recompilations. + Therefore, &ParseDepends; should only be used if scanners are not + available for the employed language or not powerful enough for the + specific task. + + + +
+ +
Ignoring Dependencies: the &Ignore; Function @@ -1492,7 +1632,7 @@ cc -o hello.o -c hello.c cc -o hello version.o hello.o % scons -Q - scons: `.' is up to date. + cc -o version.o -c version.c
-- cgit v0.12