From e24f15290b564b8fee1ce5185aa4921fc7a5fd96 Mon Sep 17 00:00:00 2001 From: stevenknight Date: Sat, 6 Sep 2008 10:35:03 +0000 Subject: [PATCH] Issue 1978: put the FindFile section in the Miscellaneous chapter. git-svn-id: http://scons.tigris.org/svn/scons/trunk@3354 fdb21ef1-2011-0410-befe-b5e4ea1792b1 --- doc/user/findfile.in | 204 ------------------------------------------- doc/user/misc.in | 185 +++++++++++++++++++++++++++++++++++++++ doc/user/misc.xml | 164 ++++++++++++++++++++++++++++++++++ 3 files changed, 349 insertions(+), 204 deletions(-) delete mode 100644 doc/user/findfile.in diff --git a/doc/user/findfile.in b/doc/user/findfile.in deleted file mode 100644 index 2b1040a8..00000000 --- a/doc/user/findfile.in +++ /dev/null @@ -1,204 +0,0 @@ - - - - - The &FindFile; function searches for a file in a list of directories. - If there is only one directory, it can be given as a simple string. - The function returns a File node if a matching file exists, - or None if no file is found. - (See the documentation for the &Glob; function for an alternative way - of searching for entries in a directory.) - - - - - - # one directory - print FindFile('missing', '.') - t = FindFile('exists', '.') - print t.__class__, t - - - exists - - - - - scons -Q - - - - - # several directories - includes = [ '.', 'include', 'src/include'] - headers = [ 'nonesuch.h', 'config.h', 'private.h', 'dist.h'] - for hdr in headers: - print '%-12s' % ('%s:' % hdr), FindFile(hdr, includes) - - - exists - - - - - - exists - - - - exists - - - - scons -Q - - - - - - - If the file exists in more than one directory, - only the first occurrence is returned. - - - - - - print FindFile('multiple', ['sub1', 'sub2', 'sub3']) - print FindFile('multiple', ['sub2', 'sub3', 'sub1']) - print FindFile('multiple', ['sub3', 'sub1', 'sub2']) - - - - exists - - - - exists - - - - exists - - - - - scons -Q - - - - - - - In addition to existing files, &FindFile; will also find derived files - (that is, non-leaf files) that haven't been built yet. - (Leaf files should already exist, or the build will fail!) - - - - - - # Neither file exists, so build will fail - Command('derived', 'leaf', 'cat >$TARGET $SOURCE') - print FindFile('leaf', '.') - print FindFile('derived', '.') - - - - - scons -Q - - - - - # Only 'leaf' exists - Command('derived', 'leaf', 'cat >$TARGET $SOURCE') - print FindFile('leaf', '.') - print FindFile('derived', '.') - - - leaf - - - - - scons -Q - - - - - If a source file exists, &FindFile; will correctly return the name - in the build directory. - - - - - - # Only 'src/leaf' exists - VariantDir('build', 'src') - print FindFile('leaf', 'build') - - - - leaf - - - - - scons -Q - diff --git a/doc/user/misc.in b/doc/user/misc.in index cb969e71..b0876062 100644 --- a/doc/user/misc.in +++ b/doc/user/misc.in @@ -231,6 +231,191 @@ +
+ Searching for Files: the &FindFile; Function + + + + The &FindFile; function searches for a file in a list of directories. + If there is only one directory, it can be given as a simple string. + The function returns a File node if a matching file exists, + or None if no file is found. + (See the documentation for the &Glob; function for an alternative way + of searching for entries in a directory.) + + + + + + # one directory + print FindFile('missing', '.') + t = FindFile('exists', '.') + print t.__class__, t + + + exists + + + + + scons -Q + + + + + # several directories + includes = [ '.', 'include', 'src/include'] + headers = [ 'nonesuch.h', 'config.h', 'private.h', 'dist.h'] + for hdr in headers: + print '%-12s' % ('%s:' % hdr), FindFile(hdr, includes) + + + exists + + + + + + exists + + + + exists + + + + scons -Q + + + + + + + If the file exists in more than one directory, + only the first occurrence is returned. + + + + + + print FindFile('multiple', ['sub1', 'sub2', 'sub3']) + print FindFile('multiple', ['sub2', 'sub3', 'sub1']) + print FindFile('multiple', ['sub3', 'sub1', 'sub2']) + + + + exists + + + + exists + + + + exists + + + + + scons -Q + + + + + + + In addition to existing files, &FindFile; will also find derived files + (that is, non-leaf files) that haven't been built yet. + (Leaf files should already exist, or the build will fail!) + + + + + + # Neither file exists, so build will fail + Command('derived', 'leaf', 'cat >$TARGET $SOURCE') + print FindFile('leaf', '.') + print FindFile('derived', '.') + + + + + scons -Q + + + + + # Only 'leaf' exists + Command('derived', 'leaf', 'cat >$TARGET $SOURCE') + print FindFile('leaf', '.') + print FindFile('derived', '.') + + + leaf + + + + + scons -Q + + + + + If a source file exists, &FindFile; will correctly return the name + in the build directory. + + + + + + # Only 'src/leaf' exists + VariantDir('build', 'src') + print FindFile('leaf', 'build') + + + + leaf + + + + + scons -Q + + +
+
Handling Nested Lists: the &Flatten; Function diff --git a/doc/user/misc.xml b/doc/user/misc.xml index c5f29b68..cd09274b 100644 --- a/doc/user/misc.xml +++ b/doc/user/misc.xml @@ -229,6 +229,170 @@
+
+ Searching for Files: the &FindFile; Function + + + + The &FindFile; function searches for a file in a list of directories. + If there is only one directory, it can be given as a simple string. + The function returns a File node if a matching file exists, + or None if no file is found. + (See the documentation for the &Glob; function for an alternative way + of searching for entries in a directory.) + + + + + # one directory + print FindFile('missing', '.') + t = FindFile('exists', '.') + print t.__class__, t + + + + % scons -Q + None + SCons.Node.FS.File exists + scons: `.' is up to date. + + + + # several directories + includes = [ '.', 'include', 'src/include'] + headers = [ 'nonesuch.h', 'config.h', 'private.h', 'dist.h'] + for hdr in headers: + print '%-12s' % ('%s:' % hdr), FindFile(hdr, includes) + + + + % scons -Q + nonesuch.h: None + config.h: config.h + private.h: src/include/private.h + dist.h: include/dist.h + scons: `.' is up to date. + + + + + + + If the file exists in more than one directory, + only the first occurrence is returned. + + + + + print FindFile('multiple', ['sub1', 'sub2', 'sub3']) + print FindFile('multiple', ['sub2', 'sub3', 'sub1']) + print FindFile('multiple', ['sub3', 'sub1', 'sub2']) + + + + % scons -Q + sub1/multiple + sub2/multiple + sub3/multiple + scons: `.' is up to date. + + + + + + + In addition to existing files, &FindFile; will also find derived files + (that is, non-leaf files) that haven't been built yet. + (Leaf files should already exist, or the build will fail!) + + + + + # Neither file exists, so build will fail + Command('derived', 'leaf', 'cat >$TARGET $SOURCE') + print FindFile('leaf', '.') + print FindFile('derived', '.') + + + + % scons -Q + None + derived + scons: *** Source `leaf' not found, needed by target `derived'. Stop. + + + + # Neither file exists, so build will fail + Command('derived', 'leaf', 'cat >$TARGET $SOURCE') + print FindFile('leaf', '.') + print FindFile('derived', '.') + + # Only 'leaf' exists + Command('derived', 'leaf', 'cat >$TARGET $SOURCE') + print FindFile('leaf', '.') + print FindFile('derived', '.') + + + + % scons -Q + leaf + derived + cat > derived leaf + + + + + If a source file exists, &FindFile; will correctly return the name + in the build directory. + + + + + # Only 'src/leaf' exists + VariantDir('build', 'src') + print FindFile('leaf', 'build') + + + + % scons -Q + build/leaf + scons: `.' is up to date. + + +
+
Handling Nested Lists: the &Flatten; Function -- 2.26.2