Copying Files

You can copy files at build time by using a copy 'file' target that specifies a set of input files and an output destination. For example:

setup: {
    from: 'web/readme.html',
    to: '${OUT}/web/',
},

This example will copy the specified readme file to the web directory under the platform output directory.

The from property may be a single filename or an array of files or directories. It may contain wildcards to match multiple files or directories. If the from property selects multiple files or if the to property is a directory, the specified files will be copied into that directory. If the to property has a trailing "/", it will be assumed to be a directory and will be created if it does not exist.

Copying Files or Trees

By default, the copy file target operates in "flatten" mode where all matching files are copied to the destination directory without copying the source directory structure. This mode is useful to copy a single file or to collect a group of files into a single output directory. When you need to copy a directory and contents, set the flatten property to false.

setup: {
    from: 'web/**',
    to: '${OUT}/public/',
    flatten: true,
},

This copies the entire web directory and contents to the public directory.

Under the Hood

File targets with from and to properties are converted to a canonical form before processing. The from property is converted to the files property and the to property is converted to the path property. The target type is also set to file. So a fully described file target actually is converted to the following:

setup: {
    files: [ 'web/readme.html' ],
    path: '${OUT}/web',
    type: 'file',
},

File Selection Patterns

The from property may be a single file or an array of files or directories. These files can include wild cards which are expanded using the Ejscript Path.files routine. The supported wild cards are:

PatternDescription
?matches any single character
*matches zero or more characters in a filename or directory
**zero or more files or directories and matches recursively in a directory tree
!negates pattern. This removes matching patterns from the file set. These are applied after all patterns have been processed. Use !! to escape a ! character or set the noneg property to to disable processing negated patterns.
/If a pattern terminates with / it will only match directories.

If a pattern in the files property is a directory, then the directory and all the files in that directory will be copied. In other words, the pattern will automatically be converted to path/**. If a pattern has a trailing "/" then the contents of the directory will be copied.

Here is an example that copies a directory and its structure, excludes temp files and trims the first part of the directory name 'web'.

setup: {
    from: [ 'web/**', '!**.tmp' ],
    to: '${OUT}/web',
    flatten: false,
    relative: 'web',
},

Stale Targets

If the destination path specified by the to or path property is is up-to-date, meaning that no input files have been modified after the destination, then the files will not be copied.

File Target Properties

File targets can modify the behavior of the copying by including other optional properties:

Property Type Description
active Boolean If a destination file is an active executable or library, rename the active file using a '.old' extension and retry.
append Boolean Set the operation to catenate input files into a single output file. Same as 'operation: "append"'
compress Boolean Compress destination files using Zlib. Results in a '.gz' extension.
divider String Divider text to use between appended files.
extension String | Path Extension to use for the destination filenames.
extensionDot String Specifies where the filename extension begins for filenames with multiple dots. Set to 'first' or 'last'.
filter RegExp Pattern of lines to filter out from appended files.
flatten Boolean Flatten the input source tree to a single level. Defaults to true.
footer String Footer to append when appending files.
group String | Number Group permission name or number to use for the destination files.
header String Header prepend when appending files.
isDir Boolean Assume the destination is a directory. Create if it does not exist. Same as appending a trailing '/' to the 'to' argument.
keep Boolean Keep uncompressed file after compressing.
operation String Set to 'append' to append files, 'copy' to copy files and 'move' to move files. Set to 'list' to return a file list in options.list and perform no operations. Defaults to 'copy' if unset.
patch Object Expand file contents tokens using this object. Object hash containing properties to use when replacing tokens of the form ${token} in file contents.
permissions Number Posix style permissions mask. E.g. 0644.
relative Boolean | String | Path Create destination filenames relative to the path provided by the 'relative' option, otherwise destination filenames include the Path value. If set to true, the destination will be relative to the current directory. If set, implies flatten == false. Defaults to false.
rename Function Callback function to provide a new destination filename. Calling sequence: Function(from, to, options): Path.
divider Boolean Keep uncompressed file after compressing.
strip Boolean Run 'strip' on the destination files.
symlink String | Path Create a symbolic link to the destination. If symlink has a trailing '/' a link is created in the directory specified by 'symlink' using the source file basename as the link name.
trim Number Number of path components to trim from the start of the source filename. If set, implies flatten == false.
user String | Number User account name or number to use for destination files.

To learn more about MakeMe, read about Creating a Configurable Project.

© Embedthis Software, 2003-2015. All rights reserved.