-
Notifications
You must be signed in to change notification settings - Fork 28
/
ProjectApi.js
281 lines (262 loc) · 11.7 KB
/
ProjectApi.js
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
/*jshint node:true, unused:false */
/**
* @class Class, that acts as abstract on top of Cordova project. Encapsulates the
* basic properties, that represents project configuration and methods for
* managing the project.
*/
function ProjectApi () {}
/**
* Gets a ProjectApi instance for specified directory.
*
* @param {String} projectDir Path to cordova project.
*
* @return {Promise<ProjectApi>} Returns a promise either fulfilled with a
* Cordova project instance or rejected with CordovaError.
*/
ProjectApi.getProjectAt = function (projectDir) {};
/**
* Initializes an empty cordova project at specified directory. Copies
*
* @param {String} targetDir Path to directory, where new project will be
* created.
* @param {String} [appName = 'HelloCordova'] Application name, that will be
* used for '<name>' element in config.xml. If not specified, 'HelloCordova'
* will be used.
* @param {String} [appId = 'io.cordova.hellocordova'] Application id in
* form of reverse domain style identifier, that will be used for 'id'
* attribute of '<widget>' element. If not specified 'io.cordova.hellocordova'
* will be used.
* @param {Object} [options] An options object. The most common options are:
* @param {String} options.wwwSource Specifies the www assets source for new
* application instead of default one. If not specified, the Cordova
* HelloWorld assets will be used.
* @param {Boolean} options.link Specifies that www source will be symlinked
* to app's directory instead of copying.
*
* @return {Promise<ProjectApi>} Returns a promise either fulfilled with a
* Cordova project instance or rejected with CordovaError.
*/
ProjectApi.createProject = function (targetDir, appName, appId, options) {};
/**
* Gets a ProjectInfo structure that describes the project.
*
* @return {CordovaProject} A CordovaProject object.
*/
ProjectApi.prototype.getProjectInfo = function () {};
/**
* Adds a new platform to project.
*
* @param {String} platformSpec A platform spec that should be one of
* following:
*
* - valid platform name: 'android', 'windows', etc.
* - valid npm identifier, that resolves to valid platform: cordova-android@4.0
* - git url, that points to repo with valid platform:
* http://github.com/apache/cordova-android.git#4.0.0
* - path to local repo of valid platform:
* /my/cordova/repositories/cordova-android
*
* @param {Object} [options] The options object. Supported properties:
* @param {Boolean} [options.saveToProject = false] Flag that indicates, that added platform
* should be saved into project configuration to be easily restored after. The
* approach is similar to 'npm install --save' command.
*
* @return {Promise} A promise either fulfilled if platform is installed
* successfully, or rejected with CordovaError.
*/
ProjectApi.prototype.addPlatform = function (platformSpec, options) {};
/**
* Removes a platform from project.
*
* @param {String} platformName A name of platform that should be removed
* from project.
* @param {Object} [options] The options object. Supported properties:
* @param {Boolean} [options.saveToProject = false] Flag that indicates, that
* platform also should be removed from project configuration.
*
* @return {Promise} A promise either fulfilled if platform is removed
* successfully, or rejected with CordovaError.
*/
ProjectApi.prototype.removePlatform = function (platformName, options) {};
/**
* Adds a new plugin into project. Installs it to each platform in project.
*
* @param {String} pluginSpec A plugin spec that should be one of following:
*
* - valid plugin id that can be resolved through either cordova
* plugin registry or npm:
* 'org.apache.cordova.globalization', 'cordova-plugin-globalization'
* - valid npm identifier, that resolves to valid plugin:
* cordova-plugin-globalization@1.0.0
* - git url, that points to repo with valid plugin:
* http://github.com/apache/cordova-plugin-globalization.git#r1.0.0
* - path to local repo of valid plugin:
* /my/cordova/repositories/cordova-plugin-globalization
*
* @param {Object} [options] An options object. Possible options are:
* @param {Boolean} saveToProject Flag that indicates, that added plugin should
* be saved into project configuration.
* @param {Boolean} link Flag that specifies that plugin sources will be
* symlinked to app's directory instead of copying if possible.
* @param {String} searchPath Valid path, that will be used to search for
* plugin in local filesystem.
* @param {Object} variables An object that represents variables that will be
* used to install plugin. See more details on plugin variables in
* documentation:
* https://cordova.apache.org/docs/en/4.0.0/plugin_ref_spec.md.html
*
* @return {Promise} A promise either fulfilled if plugin is installed
* successfully, or rejected with CordovaError.
*/
ProjectApi.prototype.addPlugin = function (pluginSpec, options) {};
/**
* Removes a plugin from project.
*
* @param {String} pluginId An id of plugin that should be removed from
* project.
* @param {Object} [options] The options object. Supported properties:
* @param {Boolean} options.saveToProject Flag that indicates, that plugin
* also should be removed from project configuration.
*
* @return {Promise} A promise either fulfilled if platform is removed
* successfully, or rejected with CordovaError.
*/
ProjectApi.prototype.removePlugin = function (pluginId, options) {};
/**
* Gets all platforms, installed into project.
*
* @return {PlatformApi[]} An array of PlatformApi instances.
*/
ProjectApi.prototype.getPlatforms = function () {};
/**
* Gets a platform by name
*
* @param {String} platformName The platform name.
*
* @return {PlatformApi} PlatformApi instance for specified platform.
*/
ProjectApi.prototype.getPlatform = function (platformName) {};
/**
* Gets all the plugins, installed into project.
*
* @return {Array<PluginInfo>} An array of PluginInfo instances.
*/
ProjectApi.prototype.getPlugins = function () {};
/**
* Gets plugins, specified by id.
*
* @return {PluginInfo} A PluginInfo instance for specified plugin.
*/
ProjectApi.prototype.getPlugin = function (pluginId) {};
/**
* Prepares a project for building specified platform/platforms. The prepare
* step is need to be performed to update configuration and www assets for
* each platform from application's ones before the application will be built.
* The prepare step isn't required if no configuration changes or www assets
* changes was made.
*
* @param {String|String[]} [platform] Single platform or array of platform
* names, that needs to be prepared. If omitted, all platform, added to
* project will be prepared.
* @param {Object} [prepareOptions] An options object with following fields:
* @param {Boolean} prepareOptions.browserify Specifies that project should be
* prepared with 'browserify' flow to embed all plugins' JS files and cordova
* JS sources into one single file.
*
* @return {Promise} A promise either fulfilled, if platform/platforms
* prepared successfully, or rejected with CordovaError otherwise.
*/
ProjectApi.prototype.prepare = function (platform, prepareOptions) {};
/**
* Builds an application package for specified platform/platforms.
*
* @param {String|String[]} [platform] A list of platform names/single name.
* If not specified, builds packages for all platforms, installed into
* project.
*
* @param {Object} [buildOptions] A build options. This object's structure is
* highly depends on platform's specific. The most common options are:
* @param {Boolean} buildOptions.debug Indicates that packages should be
* built with debug configuration. This is set to true by default unless the
* 'release' option is not specified.
* @param {Boolean} buildOptions.release Indicates that packages should be
* built with release configuration. If not set to true, debug configuration
* will be used.
* @param {Boolean} buildOptions.device Specifies that built app is intended
* to run on device
* @param {Boolean} buildOptions.emulator: Specifies that built app is
* intended to run on emulator
* @param {String} buildOptions.target Specifies the device id that will be
* used to run built application.
* @param {Boolean} buildOptions.nobuild Indicates that this should be a
* dry-run call, so no build artifacts will be produced.
* @param {String[]} buildOptions.archs Specifies chip architectures which
* app packages should be built for. List of valid architectures is depends on
* platform.
* @param {String} buildOptions.buildConfig The path to build configuration
* file. The format of this file is depends on platform.
* @param {String[]} buildOptions.argv Raw array of command-line arguments,
* passed to `build` command. The purpose of this property is to pass a
* platform-specific arguments, and eventually let platform define own
* arguments processing logic.
*
* @return {Promise<Object>} A promise either fulfilled with an array of build
* artifacts for each platform, if package was built successfully, or rejected
* with CordovaError. The keys of resultant object is a platform names, and
* values - arrays of build artifact objects. The structure of build artifacts
* is descriped in PlatformApi reference.
*/
ProjectApi.prototype.build = function (platform, buildOptions) {};
/**
* Builds and runs an application package for specified platform on specified
* device/emulator.
*
* @param {String|String[]} [platform] A list of platform names/single name.
* If omitted, method runs packages for all platforms, installed into project.
* @param {Object} [runOptions] An options object. The structure is the same
* as for build options.
*
* @return {Promise} A promise either fulfilled if application ran successfully,
* or rejected with CordovaError.
*/
ProjectApi.prototype.run = function (platform, runOptions) {};
/**
* Runs an application on a local web-server and launches a browser to display
* application content.
*
* @param {String} [platform] A platform to run server for.
* @param {Object} [serveOptions] A set of options to pass to serve command.
* Available options are:
* @param {Number} serveOptions.port A port to bind server to.
* @param {String} serveOptions.target A browser name. Available targets
* depends on platform. Most common are: 'chrome', 'safari', 'opera', 'firefox'.s
*
* @return {Promise} A promise either fulfilled, if server ran successfully,
* or rejected with CordovaError otherwise.
*/
ProjectApi.prototype.serve = function (platform, serveOptions) {};
/**
* Cleans out the build artifacts for specified platform.
*
* @param {String|String[]} [platform] A list of platform names/single
* platform, which needs to be cleaned. If not specified, run clean for all
* platforms, installed into project.
* @param {Object} [cleanOptions] An options object. The structure is not
* defined explicitly, so it can be used to pass some platfom specific vaues
* to platform.
*
* @return {Promise} A promise either fulfilled or rejected with CordovaError.
*/
ProjectApi.prototype.clean = function(platform, cleanOptions) {};
/**
* Performs a requirements check for each platforms installed. Each platform
* defines its own set of requirements, which should be resolved before
* platform can be built successfully.
*
* @param {String|String[]} [platform] A list of platform names/single
* platform, which requirements needs to be checked for.
*
* @return {Promise<Requirement[]>} Promise resolved with set of Requirement
* objects for each platform.
*/
ProjectApi.prototype.requirements = function(platform) {};