config.xml as a build artifact for less suffering and easier upgrades
Terminology
-
“platform config.xml” refers to the platform-specific config.xml files,
eg. platforms/android/res/xml/config.xml. This is the final file read by
Cordova at runtime.
-
“app config.xml” refers to the top-level config.xml found in
www/config.xml.
Why the current situation is suffering
-
Chiefly, the platforms/foo/.../config.xml files are both the input and
output of munging by Plugman and the user. This sucks. It makes
automatic upgrades difficult because everybody has a customized config.xml
file in their platforms. It also makes plugin rm harder and less robust in
CLI than it needs to be.
-
Currently only some tags in the app config.xml are actually honoured.
Others are ignored, and this has tripped up our users.
Goals
-
bin/create workflow is unchanged.
-
Final content of the platform config.xml file is unchanged, though the
method of building it in the CLI can change.
-
CLI workflow is unchanged, in terms of what a user types.
-
platform config.xml stops being both input and output under CLI. Less
munging, and easier upgrades. In short, platform config.xml files become
build artifacts.
What we propose to do about it
-
First, adjust the platform template (used by bin/create) to contain two
files:
-
defaults.xml, which is versioned, immutable, and tucked away
somewhere (only CLI accesses it) and contains only the Cordova-specified
platform defaults, such as the preferences, any default
whitelist entries,
etc. It does NOT contain any <author>, <name> or other such tags.
-
platform config.xml, which is the same as it currently is, a complete
config.xml for the HelloWorld app. This means behavior is unchanged
for people who are not using CLI. Plugman still munges this file and
outputs back to it, same as now.
-
Second, adjust the CLI’s cordova create template so that its top-level
app config.xml contains <name>, <author>, <content>, etc. - tags the
user is likely to edit.
-
Third, modify the CLI so that the new cordova prepare flow is:
-
Delete the old platform config.xml.
-
Copy the defaults.xml to config.xml.
-
Re-run the Plugman config munging for every plugin, modifying the
fresh platform config.xml. (The order here is deliberately undefined;
plugins should already not be relying on this.)
-
Run the config munging for the app’s config.xml as well.
-
This results in a freshly built, build-artifact platform config.xml.
Users should not be editing it; their top-level app config.xml
has the last
word and will override any settings the defaults or plugins might make.
-
Note that this means we shouldn’t be needlessly setting defaults
in the app config.xml, since this might prevent plugins from changing
things that need changing.
-
Fourth, extend the app config.xml format so that it can have
<platform>tags, like a plugin.xml.
-
Into this it can put platform-specific things like splashscreens,
preferences and other things, rather than mixing these together in the
config.
-
In particular, it can have <config-file> tags in the usual format
