FASTBuild - Function Reference

Copies one or more directories.

CopyDir( 'name' ) // Name (required) { // Basic options .SourcePaths // Directories to copy .Dest // Destination path // Filtering options .SourcePathsPattern // (optional) Wildcard pattern(s) to filter source files (default: "*") .SourcePathsRecurse // (optional) Recurse into source sub-directories? (default: true) .SourceExcludePaths // (optional) Source directories to ignore when recursing // Additional options .PreBuildDependencies // (optional) Force targets to be built before this CopyDir (Only // needed when other nodes output files to be copied) }

NOTE: Be sure to specify .PreBuildDependencies if copying the results of other build steps.

CopyDir() can be used to copy one or more directories to a provided new directory. By default, the source directories are recursed and all files are copied to the destination. Recursion can be controlled (.SourcePathsRecurse) and the source files can be filtered using a wildcard pattern (.SourcePathsPattern).

The directory structure relative to the source path(s) is replicated in the destination folder. Any missing destination directories are created as required. For example:

CopyDir( 'CopyExample' ) { .SourcePaths = 'folder\' .Dest = 'out\' }

With a source directory structure as follows:

folder\filea.dat folder\subdir\fileb.dat

Will be copied as:

out\filea.dat out\subdir\fileb.dat

At least one source path is required, but it is permissible for the source path(s) to contain no files.

.SourcePaths - String/ArrayOfStrings - (Required)

One or more source paths can be provided, either as a string or an array of strings. The contents of each source path will be scanned for files. Recursion can be controlled (.SourcePathsRecurse) and the source files can be filtered using a wildcard pattern (.SourcePathsPattern).

Example:

.SourcePaths = 'folder\'

Or:

.SourcePaths = { 'folderA\', 'folderB\' }

.Dest - String - (Required)

All files discovered in the .SourcePaths (subject to recursion and filtering options) will be copied to the .Dest path. The folder structure relative to the source path(s) will be re-created in the .Dest path.

Example:

.Dest = 'out\'

.SourcePathsPattern - String/ArrayOfStrings - (Optional)

One or more wildcard patterns can be specified to filter the files to be copied. The default pattern is '*'.

Example:

.SourcePathsPattern = '*.dll' // Copy only dll files

Example:

.SourcePathsPattern = { '*.dll', '*.pdb' } // Copy dll and pdb files

.SourcePathsRecurse - Bool - (Optional)

File discovery in the .SourcePaths is recursive by default. This option can be enabled or disabled explicitly.

Example:

.SourcePathsRecurse = false // disable recursion

.SourceExcludePaths - String/ArrayOfStrings - (Optional)

An optional list of source directories to ignore during the CopyDir() operation.

Example:

.SourcePaths = 'files\' .SourceExcludePaths = 'files\badfiles\' // don't copy this sub-dir

.PreBuildDependencies - String/ArrayOfStrings - (Optional)

One or more nodes which must be built before this node is built.

The .PreBuildDependencies option ensures the specified targets are up-to-date before the CopyDir() is executed. This is necessary in situations where files are generated as part of the build. Failure to specify these dependencies in this way could allow the CopyDir() operation to be performed before the source files are updated/generated. This will result in unreliable builds (wrong or missing files) or even build failure (copy attempted while source file is still being written/updated).

Example:

.SourcePaths = 'generated\scripts\' .Dest = 'out\scripts\' .PreBuildDependencies = 'GenerateScriptFiles' // Make sure scripts are generated before copy // (assuming this is a previously defined target)

For files which are present before the build starts (i.e. always on disk, or generated by some process external to the build) this option is unnecessary.