Copy

Summary

Copies one or more files.

Copy( name ) // (optional) Alias { // Basic options .Source // File(s) to copy .Dest // Destination (path or filename) // Advanced options .SourceBasePath // (optional) Base directory to copy partial relative hierarchy (see below) // Additional options .PreBuildDependencies // (optional) Force targets to be built before this Copy (Rarely needed, // but useful when Copy relies on externally generated files). }

Details

Copy() can be used to copy a single file:

Copy( 'CopyFile' ) { .Source = 'library/library.dll' .Dest = 'out/bin/' }

Or multiple files:

Copy( 'CopyFile' ) { .Source = { 'library1/library1.dll' 'library2/library2.dll' } .Dest = 'out/bin/' }

If copying a single file, the filename can be modified during the copy, by specifying .Dest as a filename instead of a path:

Copy( 'CopyFile' ) { .Source = 'bin/oldname.exe' .Dest = 'bin/newname.exe' }

Basic Options

.Source - String/ArrayOfStrings - (Required)

One or more files to be copied.

Example:

.Source = 'folder/file.ext'

Or:

.Source = { 'folder/file.a', 'folder/file.b' }

.Dest - String - (Required)

Destination for copy:

.Dest = 'out/'

If a single .Source file is specified, the .Dest can specify the destination filename:

.Dest = 'out/renamedFile.ext'

Advanced Options

.SourceBasePath - String - (Optional)

Source path to consider as root for copy. Sub-directory structure relative to this path will be replicated during copy.

Example:

.Source = { 'in/folderA/fileA.ext' 'in/folderA/subDir/fileB.ext' } .SourceBasePath = 'in/' .Dest = 'out/'

Will result in the following output structure:

out/folderA/fileA.ext out/folderA/subDir/fileB.ext

Without .SourceBasePath, the copy result would be:

out/fileA.ext out/fileB.ext

Additional Options

.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 Copy() is executed. This is necessary in situations where multiple files are generated as part of a single build step. Failure to specify these dependencies in this way could allow the Copy() 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:

.Source = { 'generated/scripts/program.exe' 'generated/scripts/program.pdb' } .Dest = 'bin/' .PreBuildDependencies = 'Compile' // Make sure exe completes (so pdb is written before copy) // (assuming this is a previously defined target)

For single file targets previously defined in the build, or 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.