dirkbaechle avatar dirkbaechle committed 3612f1f

- improved docs for return value of custom Scanners (#2713)

Comments (0)

Files changed (5)

 to the
 .B SourceFileScanner
 object.
-See the section "Scanner Objects,"
+See the section "Scanner Objects"
 below, for more information about
 defining your own Scanner objects
 and using the
 based only on the target file
 and the construction environment,
 .I not
-for implicit
-(See the section "Scanner Objects," below,
+for implicit dependencies based on source files.
+(See the section "Scanner Objects" below,
 for information about creating Scanner objects.)
 
 .IP source_scanner
 A Scanner object that
 will be invoked to
-find implicit dependences in
+find implicit dependencies in
 any source files
 used to build this target file.
 This is where you would
 that
 .B scons
 does not know about from other Builder or function calls.
-(See the section "Scanner Objects," below,
+(See the section "Scanner Objects" below,
 for information about creating your own Scanner objects.)
 
 .IP target_factory
 (In fact, this is how the above modifiers are substituted,
 they are simply attributes of the Python objects
 that represent TARGET, SOURCES, etc.)
-See the section "Python Code Substitution," below,
+See the section "Python Code Substitution" below,
 for more thorough examples of
 how this can be used.
 
 This can be either:
 1) a Python function that will process
 the Node (file)
-and return a list of strings (file names)
+and return a list of File Nodes
 representing the implicit
-dependencies found in the contents;
+dependencies (file names) found in the contents;
 or:
 2) a dictionary that maps keys
 (typically the file suffix, but see below for more discussion)
 
 XYZScanner = Scanner(xyz_scan)
 
-SourceFileScanner.add_scanner('.xyx', XYZScanner)
+SourceFileScanner.add_scanner('.xyz', XYZScanner)
 
 env.Program('my_prog', ['file1.c', 'file2.f', 'file3.xyz'])
 .EE
 def kfile_scan(node, env, path, arg):
     contents = node.get_text_contents()
     includes = include_re.findall(contents)
-    return includes
+    return env.File(includes)
 
 kscan = Scanner(name = 'kfile',
                 function = kfile_scan,
 bar_in.target_scanner = kscan
 .EE
 
+It is important to note that you
+have to return a list of File nodes from the scan function, simple
+strings for the file names won't do. As in the examples we are showing here,
+you can use the
+.BR File()
+function of your current Environment in order to create nodes on the fly from
+a sequence of file names with relative paths.
+
 Here is a similar but more complete example that searches
 a path of directories
 (specified as the
 for files that actually exist:
 
 .ES
+import re
+import os
 include_re = re.compile(r'^include\\s+(\\S+)$', re.M)
 
 def my_scan(node, env, path, arg):
-   contents = node.get_text_contents()
-   includes = include_re.findall(contents)
-   if includes == []:
+    contents = node.get_text_contents()
+    includes = include_re.findall(contents)
+    if includes == []:
         return []
     results = []
     for inc in includes:
         for dir in path:
-            file = dir + os.sep + inc
+            file = str(dir) + os.sep + inc
             if os.path.exists(file):
                 results.append(file)
                 break
-    return results
+    return env.File(results)
 
 scanner = Scanner(name = 'myscanner',
                  function = my_scan,
                  argument = None,
                  skeys = ['.x'],
-                 path_function = FindPathDirs('MYPATH'),
+                 path_function = FindPathDirs('MYPATH')
                  )
 scanners = Environment().Dictionary('SCANNERS')
-env = Environment(SCANNERS = scanners + [scanner])
+env = Environment(SCANNERS = scanners + [scanner],
+                  MYPATH = ['incs'])
+
+env.Command('foo', 'foo.x', 'xprocess < $SOURCES > $TARGET')
 .EE
 
 The
 that will return a list of directories
 specified in the
 .B $MYPATH
-construction variable.
+construction variable. It lets SCons detect the file
+.B incs/foo.inc
+, even if 
+.B foo.x 
+contains the line
+.B include foo.inc 
+only.
 If you need to customize how the search path is derived,
 you would provide your own
 .B path_function
                  function = my_scan,
                  argument = None,
                  skeys = ['.x'],
-                 path_function = pf,
+                 path_function = pf
                  )
 .EE
 

doc/user/scanners.in

       
       def kfile_scan(node, env, path, arg):
           contents = node.get_text_contents()
-          return include_re.findall(contents)
+          return env.File(include_re.findall(contents))
     </programlisting>
 
     <para>
+    
+      It is important to note that you
+      have to return a list of File nodes from the scanner function, simple
+      strings for the file names won't do. As in the examples we are showing here,
+      you can use the &File;
+      function of your current Environment in order to create nodes on the fly from
+      a sequence of file names with relative paths.
+      
+    </para>
+
+    <para>
 
       The scanner function must
       accept the four specified arguments
         def kfile_scan(node, env, path):
             contents = node.get_text_contents()
             includes = include_re.findall(contents)
-            return includes
+            return env.File(includes)
 
         kscan = Scanner(function = kfile_scan,
                         skeys = ['.k'])

doc/user/scanners.xml

       
       def kfile_scan(node, env, path, arg):
           contents = node.get_text_contents()
-          return include_re.findall(contents)
+          return env.File(include_re.findall(contents))
     </programlisting>
 
     <para>
+    
+      It is important to note that you
+      have to return a list of File nodes from the scanner function, simple
+      strings for the file names won't do. As in the examples we are showing here,
+      you can use the &File;
+      function of your current Environment in order to create nodes on the fly from
+      a sequence of file names with relative paths.
+      
+    </para>
+
+    <para>
 
       The scanner function must
       accept the four specified arguments
         def kfile_scan(node, env, path):
             contents = node.get_text_contents()
             includes = include_re.findall(contents)
-            return includes
+            return env.File(includes)
 
         kscan = Scanner(function = kfile_scan,
                         skeys = ['.k'])
 
         The GNU toolchain support in previous versions of SCons would
         add the -fPIC flag to the $SHCXXFLAGS construction variable.
-        The -fPIC flag has been now been removed from the default
+        The -fPIC flag has now been removed from the default
         $SHCXXFLAGS setting.  Instead, the $SHCXXCOM construction variable
         (the default SCons command line for compiling shared objects
         from C++ source files) has been changed to add the $SHCCFLAGS
     - XML fixes in User's Guide.
     - Fixed the detection of 'jar' and 'rmic' during
       the initialization of the respective Tools (#2730).
+    - Improved docs for custom Decider functions and
+      custom Scanner objects (#2711, #2713).
 
   From Joe Zuntz:
 
Tip: Filter by directory path e.g. /media app.js to search for public/media/app.js.
Tip: Use camelCasing e.g. ProjME to search for ProjectModifiedEvent.java.
Tip: Filter by extension type e.g. /repo .js to search for all .js files in the /repo directory.
Tip: Separate your search with spaces e.g. /ssh pom.xml to search for src/ssh/pom.xml.
Tip: Use ↑ and ↓ arrow keys to navigate and return to view the file.
Tip: You can also navigate files with Ctrl+j (next) and Ctrl+k (previous) and view the file with Ctrl+o.
Tip: You can also navigate files with Alt+j (next) and Alt+k (previous) and view the file with Alt+o.