raptor/notes/extended_export.txt

Overview
--------

Raptor bld.inf processing now recognises the :xexport prefix within export
sections to denote an "Extended export".  Extended exports support whole
directory copies (optionally recursive) with wildcard filename matching of
source files.

Syntax
------

:xexport requires both a source directory and a destination directory with
which to operate, and optionally takes arguments in square brackets of the
form ':xexport[option1=value option2=value optionN=value]'.

Initially supported arguments are:

match="filename pattern match": limits copies to source files matching
a pattern - supports "*" (multiple character) and "?" (single character)
wildcards.  Not using 'match' is the equivalent to specifying [match="*"].

recursive=true|false: if 'true', applies operations to sub-directories
found at the source directory onwards.  Not using 'recursive' is the
equivalent to specifying [recursive=false]

Argument order is not significant.

This gives the following general syntax:

    PRJ_EXPORTS
    :xexport[match="filename_match" recursive=true|false] source_dir dest_dir
    
    PRJ_TESTEXPORTS
    :xexport[match="filename_match" recursive=true|false] source_dir dest_dir

Examples
--------

File System - Source

    /component/bld.inf
    /component/dir1/file1dir1.txt
    /component/dir1/file2dir1.txt
    /component/dir1/dir2/file1dir2.txt
    /component/dir1/dir2/file2dir2.txt
    /component/dir1/dir2/dir3/file1dir3.txt
    /component/dir1/dir2/dir3/file2dir3.txt

/component/bld.inf

    PRJ_EXPORTS
    
    dir1/file1dir1.txt                           destdir1
    :xexport dir1/dir2                           destdir2
    :xexport[recursive=true] dir1/dir2           destdir3
    :xexport[match="*1dir?.txt"] dir1/dir2       destdir4
    :xexport[match="*1dir?.txt" recursive=true]  dir1/dir2  destdir5/subdir

File System - Destination

    $EPOCROOT/epoc32/include/destdir1/file1dir1.txt

    $EPOCROOT/epoc32/include/destdir2/file1dir2.txt
    $EPOCROOT/epoc32/include/destdir2/file2dir2.txt

    $EPOCROOT/epoc32/include/destdir3/file1dir2.txt
    $EPOCROOT/epoc32/include/destdir3/file2dir2.txt
    $EPOCROOT/epoc32/include/destdir3/dir3/file1dir3.txt
    $EPOCROOT/epoc32/include/destdir3/dir3/file2dir3.txt

    $EPOCROOT/epoc32/include/destdir4/file1dir2.txt

    $EPOCROOT/epoc32/include/destdir5/subdir/file1dir2.txt
    $EPOCROOT/epoc32/include/destdir5/subdir/dir3/file1dir3.txt

Notes
-----

* Extended exports ignore symbolic link to directories (on host OSs that
  support them)
* Destination locations are resolved as directories using the same rules that
  apply to normal exports e.g. implicit $EPOCROOT/epoc32/include off-sets if no
  destination is given, etc.
* Pattern matches listed using 'match' apply to files only, not directories
* As with normal exports, source files must exist if they are to be exported
  to their destination in the same build