supd is a source file update utility that copies files from a source directory tree to a target directory tree. The files to be copied are specified in an XML file that is by default named supd.xml and located in the current directory. Thus supd can be thought to pull files from the source directory tree to the current directory and its subdirectories.
If we have a source directory tree and a target directory tree and we want to update target directory tree from the source directory tree, but we have made local changes to the project files in the target directory tree that we want not to be overwritten, we can use supd to copy just the source files and leave the project files as is.
Thus we may have the following situation where C:\source represents the source directory tree and C:\target represents the target directory tree:
C:\source
|
.--- doc
| |
| .--- file
| | |
| | .--- hello.cpp.html
| | .--- hello.hpp.html
| |
| .--- html
| |
| .--- hello.html
|
.--- hello
|
.--- hello.cpp
.--- hello.hpp
.--- hello.vcxproj
C:\target
|
.--- doc
|
.--- hello
|
.--- hello.hpp
.--- hello.vcxproj
First of all we can create a skeleton supd.xml from the contents of the source directory by running supd with the --make option:
C:\source>supd --make --verbose
make: C:/source/supd.xml
add: doc
add: hello
==> C:/source/supd.xml
The contents of the resulting supd.xml is as follows:
<supd>
<dir name="doc"/>
<dir name="hello"/>
</supd>
Since the source directory tree contains two kinds of directories: C++ source file directories and HTML documentation directories, we create pattern elements to supd.xml that reflect this:
<supd>
<pattern name="c++">
<file include="*.cpp"/>
<file include="*.hpp"/>
</pattern>
<pattern name="html">
<file include="*.html"/>
<dir include="*"/>
</pattern>
<dir name="doc"/>
<dir name="hello"/>
</supd>
The pattern elements can contain file patterns and directory patterns. Since we want to include *.cpp and *.hpp files we write those file patterns as values of the include attributes of the file child elements of the c++ pattern element. Since we want to include *.html files we write *.html as the value of the include attribute of the file child element of the html pattern element. Since we want to include all HTML directories we write "*" directory pattern as the value of the include attribute of the dir child element of the html pattern element.
Next we set the top-level dir elements to refer to these patterns by adding pattern attributes to the dir elements:
<supd>
<pattern name="c++">
<file include="*.cpp"/>
<file include="*.hpp"/>
</pattern>
<pattern name="html">
<file include="*.html"/>
<dir include="*"/>
</pattern>
<dir name="doc" pattern="html" includeSubdirs="true"/>
<dir name="hello" pattern="c++"/>
</supd>
Since we want to include subdirectories of the doc directory we add an includeSubdirs attribute with value true to the doc dir element.
Now we copy the supd.xml to the C:\target directory. We run supd with the --verbose and --from options from the C:\target directory to find out what changes would be made without making any changes:
C:\target>supd --verbose --from=C:\source
The supd program generates the following log output:
reading patterns from C:/target/supd.xml
reading dirs from C:/target/supd.xml
from C:/source/doc
from C:/source/doc/file
to be added: C:/target/doc/file/hello.cpp.html
to be added: C:/target/doc/file/hello.hpp.html
from C:/source/doc/html
to be added: C:/target/doc/html/hello.html
from C:/source/hello
to be added: C:/target/hello/hello.cpp
to be updated: C:/target/hello/hello.hpp
4 files to be added
1 files to be updated
Since we want these changes to be made, we now run the supd program with --add and --update options:
C:\target>supd --verbose --add --update --from=C:\source
supd copies files, creates directories to the target directory tree and generates the following log output:
reading patterns from C:/target/supd.xml
reading dirs from C:/target/supd.xml
from C:/source/doc
from C:/source/doc/file
added: C:/target/doc/file
added: C:/target/doc/file/hello.cpp.html
added: C:/target/doc/file/hello.hpp.html
from C:/source/doc/html
added: C:/target/doc/html
added: C:/target/doc/html/hello.html
from C:/source/hello
added: C:/target/hello/hello.cpp
updated: C:/target/hello/hello.hpp
4 files added
1 files updated
Now the target directory tree is in sync with the source directory tree:
C:\target
|
.--- doc
| |
| .--- file
| | |
| | .--- hello.cpp.html
| | .--- hello.hpp.html
| |
| .--- html
| |
| .--- hello.html
|
.--- hello
|
.--- hello.cpp
.--- hello.hpp
.--- hello.vcxproj
The root element of the supd.xml is named supd.
The root element can contain:
The pattern element must have a name attribute with any value. The name of the pattern is used to connect it to any number of top-level dir elements.
The pattern element can have
A file child element must have either an include or an exclude attribute whose value is a pattern expression. The file child elements are matched from top to bottom against file names of a source directory. Initially no file name is included. If the name of a source file matches the pattern expression of a file child element, then if the pattern expression is as the value of an
A dir child element must also have either an include or an exclude attribute whose value is a pattern expression. The dir child elements are matched from top to bottom against subdirectory names of a source directory. Initially no subdirectory name is included and the last matching directory pattern stays in effect in the same way as for file patterns.
<pattern name="source">
<file include="*.cpp"/>
<file include="*.hpp"/>
<dir include="*"/>
<dir exclude="x64"/>
<dir exclude="Debug"/>
<dir exclude="Release"/>
</pattern>
The source pattern would match *.cpp and *.hpp files and all subdirectories except x64, Debug and Release.
A pattern expression is limited form of a regular expression, where '*' matches any number of any characters and '.' matches '.' literally. In addition regular expression operator characters '*', '|', '+', '?', '(' and ')' must be escaped with a backslash if their literal meaning is intended.
| pattern‑expression | → | alternative |
| alternative | → | catenation (| catenation)* |
| catenation | → | rep rep* |
| rep | → | primary | escape | anything |
| primary | → | 'any character except '*', '|', '+', '?', '(', ')'' | escape | → | \ 'any character' |
| anything | → | * |
A top-level dir element must have a name attribute. Then a subdirectory of the root source directory tree having that name is included for processing. Note that the value of the name attribute must be single subdirectory name - no pattern expression is accepted in this case.
A top-level dir element must also have a pattern attribute whose value connects it with a pattern of that name. This means that the source files and subdirectories are matched according to the file and dir elements contained by that pattern.
A top-level dir element can have an includeSubdirs attribute with value true or false. By default subdirectories are not included.
<dir name="code" pattern="source" includeSubdirs="true"/>
The code subdirectory of the root source directory is processed according to the pattern whose name is source and its subdirectories are also processed according to that pattern.
If the program is run without --add and --update options, it shows additions and updates to be made without making changes.
If the program is run without 'file.xml' is uses 'supd.xml' from the current directory.
The program copies files from a source root directory and its subdirectories to the current directory and its subdirectories, if the current directory contains the default 'supd.xml', or to the target directory that contains a 'file.xml'.
Files to be copied are specified in the file.xml|supd.xml.
Options:| --verbose | -v | Be verbose. |
| --make | -m | Make supd.xml. |
| --force | -f | Force make. |
| --add | -a | Add new files. |
| --update | -u | Update changed files. |
| --colors=(true|false) | -c=(true|false) | Use colors in log output. |
| --from | Set source root directory. | |
| --help | -h | Print help and exit. |
HTML reference documentation.