88 See http://swift.org/CONTRIBUTORS.txt for Swift project authors
99 */
1010
11- /// Constructs commands to run during the build, including full command lines.
12- /// All paths should be based on the ones passed to the plugin in the target
13- /// build context.
11+ /// Constructs commands to run during the build, including command lines,
12+ /// environment variables, initial working directory, etc. All paths should
13+ /// be based on the ones passed to the plugin in the target build context.
1414public final class CommandConstructor {
15+
1516 /// Prevents the CommandConstructor from being instantiated by the script.
1617 internal init ( ) { }
1718
1819 /// Creates a command to run during the build. The executable should be a
19- /// path returned by `TargetBuildContext.tool(named:)`, the inputs should
20- /// be the files that are used by the command, and the outputs should be
21- /// the files that are produced by the command.
22- public func createBuildCommand(
20+ /// tool returned by `TargetBuildContext.tool(named:)`, and any paths in
21+ /// the arguments list as well as in the input and output lists should be
22+ /// based on the paths provided in the target build context structure.
23+ ///
24+ /// The build command will run whenever its outputs are missing or if its
25+ /// inputs have changed since the command was last run. In other words,
26+ /// it is incorporated into the build command graph.
27+ ///
28+ /// This is the preferred kind of command to create when the outputs that
29+ /// will be generated are known ahead of time.
30+ ///
31+ /// - parameters:
32+ /// - displayName: An optional string to show in build logs and other
33+ /// status areas.
34+ /// - executable: The executable to be invoked; should be a tool looked
35+ /// up using `tool(named:)`, which may reference either a tool provided
36+ /// by a binary target or build from source.
37+ /// - arguments: Arguments to be passed to the tool. Any paths should be
38+ /// based on the paths provided in the target build context.
39+ /// - environment: Any custom environment assignments for the subprocess.
40+ /// - inputFiles: Input files to the build command. Any changes to the
41+ /// input files cause the command to be rerun.
42+ /// - outputFiles: Output files that should be processed further according
43+ /// to the rules defined by the build system.
44+ public func addBuildCommand(
2345 displayName: String ? ,
2446 executable: Path ,
2547 arguments: [ String ] ,
26- environment: [ String : String ] ? = nil ,
48+ environment: [ String : String ] = [ : ] ,
2749 inputFiles: [ Path ] = [ ] ,
2850 outputFiles: [ Path ] = [ ]
2951 ) {
3052 output. buildCommands. append ( BuildCommand ( displayName: displayName, executable: executable, arguments: arguments, environment: environment, workingDirectory: nil , inputFiles: inputFiles, outputFiles: outputFiles) )
3153 }
3254
55+ /// Creates a command to run during the build. The executable should be a
56+ /// tool returned by `TargetBuildContext.tool(named:)`, and any paths in
57+ /// the arguments list as well as in the input and output lists should be
58+ /// based on the paths provided in the target build context structure.
59+ ///
60+ /// The build command will run whenever its outputs are missing or if its
61+ /// inputs have changed since the command was last run. In other words,
62+ /// it is incorporated into the build command graph.
63+ ///
64+ /// This is the preferred kind of command to create when the outputs that
65+ /// will be generated are known ahead of time.
66+ ///
67+ /// - parameters:
68+ /// - displayName: An optional string to show in build logs and other
69+ /// status areas.
70+ /// - executable: The executable to be invoked; should be a tool looked
71+ /// up using `tool(named:)`, which may reference either a tool provided
72+ /// by a binary target or build from source.
73+ /// - arguments: Arguments to be passed to the tool. Any paths should be
74+ /// based on the paths provided in the target build context.
75+ /// - environment: Any custom environment assignments for the subprocess.
76+ /// - workingDirectory: Optional initial working directory of the command.
77+ /// - inputFiles: Input files to the build command. Any changes to the
78+ /// input files cause the command to be rerun.
79+ /// - outputFiles: Output files that should be processed further according
80+ /// to the rules defined by the build system.
3381 @available ( * , unavailable, message: " specifying the initial working directory for a command is not yet supported " )
34- public func createBuildCommand (
82+ public func addBuildCommand (
3583 displayName: String ? ,
3684 executable: Path ,
3785 arguments: [ String ] ,
38- environment: [ String : String ] ? = nil ,
86+ environment: [ String : String ] = [ : ] ,
3987 workingDirectory: Path ? = nil ,
4088 inputFiles: [ Path ] = [ ] ,
4189 outputFiles: [ Path ] = [ ]
@@ -44,25 +92,80 @@ public final class CommandConstructor {
4492 }
4593
4694 /// Creates a command to run before the build. The executable should be a
47- /// path returned by `TargetBuildContext.tool(named:)`, the output direc-
48- /// tory should be a directory in which the command will create the output
49- /// files that should be subject to further processing.
50- public func createPrebuildCommand(
95+ /// tool returned by `TargetBuildContext.tool(named:)`, and any paths in
96+ /// the arguments list and the output files directory should be based on
97+ /// the paths provided in the target build context structure.
98+ ///
99+ /// The build command will run before the build starts, and is allowed to
100+ /// create an arbitrary set of output files based on the contents of the
101+ /// inputs.
102+ ///
103+ /// Because prebuild commands are run on every build, they are can have
104+ /// significant performance impact and should only be used when there is
105+ /// no way to know the names of the outputs before the command is run.
106+ ///
107+ /// The `outputFilesDirectory` parameter is the path of a directory into
108+ /// which the command will write its output files. Any files that are in
109+ /// that directory after the prebuild command finishes will be interpreted
110+ /// according to same build rules as for sources.
111+ ///
112+ /// - parameters:
113+ /// - displayName: An optional string to show in build logs and other
114+ /// status areas.
115+ /// - executable: The executable to be invoked; should be a tool looked
116+ /// up using `tool(named:)`, which may reference either a tool provided
117+ /// by a binary target or build from source.
118+ /// - arguments: Arguments to be passed to the tool. Any paths should be
119+ /// based on the paths provided in the target build context.
120+ /// - environment: Any custom environment assignments for the subprocess.
121+ /// - outputFilesDirectory: A directory into which the command can write
122+ /// output files that should be processed further.
123+ public func addPrebuildCommand(
51124 displayName: String ? ,
52125 executable: Path ,
53126 arguments: [ String ] ,
54- environment: [ String : String ] ? = nil ,
127+ environment: [ String : String ] = [ : ] ,
55128 outputFilesDirectory: Path
56129 ) {
57130 output. prebuildCommands. append ( PrebuildCommand ( displayName: displayName, executable: executable, arguments: arguments, environment: environment, workingDirectory: nil , outputFilesDirectory: outputFilesDirectory) )
58131 }
59132
133+ /// Creates a command to run before the build. The executable should be a
134+ /// tool returned by `TargetBuildContext.tool(named:)`, and any paths in
135+ /// the arguments list and the output files directory should be based on
136+ /// the paths provided in the target build context structure.
137+ ///
138+ /// The build command will run before the build starts, and is allowed to
139+ /// create an arbitrary set of output files based on the contents of the
140+ /// inputs.
141+ ///
142+ /// Because prebuild commands are run on every build, they are can have
143+ /// significant performance impact and should only be used when there is
144+ /// no way to know the names of the outputs before the command is run.
145+ ///
146+ /// The `outputFilesDirectory` parameter is the path of a directory into
147+ /// which the command will write its output files. Any files that are in
148+ /// that directory after the prebuild command finishes will be interpreted
149+ /// according to same build rules as for sources.
150+ ///
151+ /// - parameters:
152+ /// - displayName: An optional string to show in build logs and other
153+ /// status areas.
154+ /// - executable: The executable to be invoked; should be a tool looked
155+ /// up using `tool(named:)`, which may reference either a tool provided
156+ /// by a binary target or build from source.
157+ /// - arguments: Arguments to be passed to the tool. Any paths should be
158+ /// based on the paths provided in the target build context.
159+ /// - environment: Any custom environment assignments for the subprocess.
160+ /// - workingDirectory: Optional initial working directory of the command.
161+ /// - outputFilesDirectory: A directory into which the command can write
162+ /// output files that should be processed further.
60163 @available ( * , unavailable, message: " specifying the initial working directory for a command is not yet supported " )
61164 public func createPrebuildCommand(
62165 displayName: String ? ,
63166 executable: Path ,
64167 arguments: [ String ] ,
65- environment: [ String : String ] ? = nil ,
168+ environment: [ String : String ] = [ : ] ,
66169 workingDirectory: Path ? = nil ,
67170 outputFilesDirectory: Path
68171 ) {
0 commit comments