diff options
author | Steven Knight <knight@baldmt.com> | 2008-09-06 10:35:03 (GMT) |
---|---|---|
committer | Steven Knight <knight@baldmt.com> | 2008-09-06 10:35:03 (GMT) |
commit | 96823f98b3ca69ae84cbfd9115378a7e033a0cc1 (patch) | |
tree | 24793a91d342c5e8dbcbfbbbed79f466eba625a8 /doc/user/misc.in | |
parent | 017016eeb937d1d2bd251dd89b667de7a5e9dab7 (diff) | |
download | SCons-96823f98b3ca69ae84cbfd9115378a7e033a0cc1.zip SCons-96823f98b3ca69ae84cbfd9115378a7e033a0cc1.tar.gz SCons-96823f98b3ca69ae84cbfd9115378a7e033a0cc1.tar.bz2 |
Issue 1978: put the FindFile section in the Miscellaneous chapter.
Diffstat (limited to 'doc/user/misc.in')
-rw-r--r-- | doc/user/misc.in | 185 |
1 files changed, 185 insertions, 0 deletions
diff --git a/doc/user/misc.in b/doc/user/misc.in index cb969e7..b087606 100644 --- a/doc/user/misc.in +++ b/doc/user/misc.in @@ -232,6 +232,191 @@ </section> <section> + <title>Searching for Files: the &FindFile; Function</title> + + <para> + + 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.) + + </para> + + <scons_example name="FindFile1a"> + <file name="SConstruct" printme="1"> + # one directory + print FindFile('missing', '.') + t = FindFile('exists', '.') + print t.__class__, t + </file> + <file name="exists"> + exists + </file> + </scons_example> + + <scons_output example="FindFile1a" os="posix"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + <scons_example name="FindFile1b"> + <file name="SConstruct" printme="1"> + # 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) + </file> + <file name="config.h"> + exists + </file> + <directory name="src"></directory> + <directory name="src/include"></directory> + </file> + <file name="src/include/private.h"> + exists + <directory name="include"></directory> + </file> + <file name="include/dist.h"> + exists + </scons_example> + + <scons_output example="FindFile1b" os="posix"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + <!-- The man page says this should work, but it fails. + <para> + + If the 'file' parameter is a list of files, + a list of File nodes is returned. + + </para> + + <scons_example name="FindFile1c"> + <file name="SConstruct" printme="1"> + # several directories + includes = [ '.', 'include', 'src/include'] + headers = [ 'nonesuch.h', 'config.h', 'private.h', 'dist.h'] + print FindFile(headers, includes) + </file> + <file name="config.h"> + exists + </file> + <directory name="src"></directory> + <directory name="src/include"></directory> + </file> + <file name="src/include/private.h"> + exists + <directory name="include"></directory> + </file> + <file name="include/dist.h"> + exists + </scons_example> + + <scons_output example="FindFile1c" os="posix"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + --> + + <para> + + If the file exists in more than one directory, + only the first occurrence is returned. + + </para> + + <scons_example name="FindFile1d"> + <file name="SConstruct" printme="1"> + print FindFile('multiple', ['sub1', 'sub2', 'sub3']) + print FindFile('multiple', ['sub2', 'sub3', 'sub1']) + print FindFile('multiple', ['sub3', 'sub1', 'sub2']) + </file> + <directory name="sub1"></directory> + <file name="sub1/multiple"> + exists + </file> + <directory name="sub2"></directory> + <file name="sub2/multiple"> + exists + </file> + <directory name="sub3"></directory> + <file name="sub3/multiple"> + exists + </file> + </scons_example> + + <scons_output example="FindFile1d" os="posix"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + <!-- file may be a list of file names or a single file name. --> + + <para> + + 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!) + + </para> + + <scons_example name="FindFile2"> + <file name="SConstruct" printme="1"> + # Neither file exists, so build will fail + Command('derived', 'leaf', 'cat >$TARGET $SOURCE') + print FindFile('leaf', '.') + print FindFile('derived', '.') + </file> + </scons_example> + + <scons_output example="FindFile2" os="posix"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + <scons_example name="FindFile2"> + <file name="SConstruct" printme="1"> + # Only 'leaf' exists + Command('derived', 'leaf', 'cat >$TARGET $SOURCE') + print FindFile('leaf', '.') + print FindFile('derived', '.') + </file> + <file name="leaf"> + leaf + </file> + </scons_example> + + <scons_output example="FindFile2" os="posix"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + <para> + + If a source file exists, &FindFile; will correctly return the name + in the build directory. + + </para> + + <scons_example name="FindFile3"> + <file name="SConstruct" printme="1"> + # Only 'src/leaf' exists + VariantDir('build', 'src') + print FindFile('leaf', 'build') + </file> + <directory name="src"></directory> + <file name="src/leaf"> + leaf + </file> + </scons_example> + + <scons_output example="FindFile3" os="posix"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + </section> + + <section> <title>Handling Nested Lists: the &Flatten; Function</title> <para> |