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:

Pattern	Description
?	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.