refactor(template): Copy CordovaLib into a packages folder (#1522)

Pointing a relative path to CordovaLib in the node_modules folder means
that the Xcode project is no longer self-contained, which is significant
change in terms of assumptions people can make about the project files
in CI environments (i.e., preparing all platforms once, then copying
just the platform folders to different runners to build).

So we now copy the CordovaLib folder into a platforms/ios/packages
directory and point to it there.

As a side effect, it seemed worth bringing back the `--link` option to
continue pointing to node_modules for easier development.

lib/Api.js

@@ -107,6 +107,8 @@ class Api {
      * @param  {Object}  [options]  An options object. The most common options are:
      * @param  {String}  [options.customTemplate]  A path to custom template, that
      *   should override the default one from platform.
+     * @param  {Boolean}  [options.link]  Flag that indicates that platform's
+     *   sources will be linked to installed platform instead of copying.
      * @param {EventEmitter} [events] An EventEmitter instance that will be used for
      *   logging purposes. If no EventEmitter provided, all events will be logged to
      *   console

lib/create.js

@@ -31,7 +31,7 @@ const ROOT = path.join(__dirname, '..');
  * @param {string} project_path Path to your new Cordova iOS project
  * @param {string} package_name Package name, following reverse-domain style convention
  * @param {string} project_name Project name
- * @param {{ customTemplate: string }} opts Project creation options
+ * @param {{ link: boolean, customTemplate: string }} opts Project creation options
  * @param {ConfigParser} root_config The application config.xml
  * @returns {Promise<void>} resolves when the project has been created
  */
@@ -57,6 +57,7 @@ exports.createProject = async (project_path, package_name, project_name, opts, r
         },
         options: {
             templatePath: opts.customTemplate || path.join(ROOT, 'templates', 'project'),
+            linkLib: !!opts.link,
             rootConfig: root_config
         }
     }).create();
@@ -84,6 +85,13 @@ class ProjectCreator {
         const r = this.projectPath('App');
         fs.renameSync(path.join(r, 'gitignore'), path.join(r, '.gitignore'));
         fs.cpSync(path.join(r, '.gitignore'), this.projectPath('.gitignore'));
+
+        if (!this.options.linkLib) {
+            // Copy CordovaLib into the packages folder
+            fs.mkdirSync(this.projectPath('packages', 'cordova-ios'), { recursive: true });
+            fs.cpSync(path.join(ROOT, 'CordovaLib'), this.projectPath('packages', 'cordova-ios', 'CordovaLib'), { recursive: true });
+            fs.cpSync(path.join(ROOT, 'Package.swift'), this.projectPath('packages', 'cordova-ios', 'Package.swift'));
+        }
     }
 
     provideCordovaJs () {
@@ -133,7 +141,14 @@ class ProjectCreator {
                 }
 
                 if (ref.relativePath?.match(/\/cordova-ios/)) {
-                    ref.relativePath = `"${path.relative(this.project.path, ROOT).replaceAll(path.sep, path.posix.sep)}"`;
+                    let relPath = path.relative(this.project.path, this.projectPath('packages', 'cordova-ios'));
+
+                    if (this.options.linkLib) {
+                        // Point to CordovaLib in node_modules
+                        relPath = path.relative(this.project.path, ROOT);
+                    }
+
+                    ref.relativePath = `"${relPath.replaceAll(path.sep, path.posix.sep)}"`;
                     break;
                 }
             }

tests/spec/unit/create.spec.js

@@ -40,7 +40,7 @@ const templateConfigXmlPath = path.join(__dirname, '..', '..', '..', 'templates'
  * @param {String} tmpDir
  * @param {String} projectName
  */
-function verifyProjectFiles (tmpDir, projectName) {
+function verifyProjectFiles (tmpDir, projectName, linked) {
     expect(fs.existsSync(path.join(tmpDir, 'App'))).toBe(true);
     expect(fs.existsSync(path.join(tmpDir, 'App.xcodeproj'))).toBe(true);
     expect(fs.existsSync(path.join(tmpDir, 'App.xcworkspace'))).toBe(true);
@@ -50,7 +50,8 @@ function verifyProjectFiles (tmpDir, projectName) {
     xcodeproj.parseSync();
 
     const packageLoc = path.dirname(require.resolve('../../../package.json'));
-    const relativePath = path.relative(tmpDir, packageLoc).replaceAll(path.sep, path.posix.sep);
+    const relativeLink = path.relative(tmpDir, packageLoc).replaceAll(path.sep, path.posix.sep);
+    const relativePath = path.posix.join('packages', 'cordova-ios');
 
     let foundRef = false;
     const pkgRefs = xcodeproj.hash.project.objects.XCLocalSwiftPackageReference;
@@ -61,7 +62,11 @@ function verifyProjectFiles (tmpDir, projectName) {
 
         if (ref.relativePath.match(/\/cordova-ios/)) {
             foundRef = true;
-            expect(ref.relativePath).toMatch(relativePath);
+            if (linked) {
+                expect(ref.relativePath).toMatch(relativeLink);
+            } else {
+                expect(ref.relativePath).toMatch(relativePath);
+            }
             break;
         }
     }
@@ -104,11 +109,11 @@ function verifyProjectDeploymentTarget (tmpDir, expectedTarget) {
  * @param {String} projectName
  * @returns {Promise}
  */
-async function verifyCreatedProject (tmpDir, packageName, projectName, configFile = templateConfigXmlPath) {
+async function verifyCreatedProject (tmpDir, packageName, projectName, link = false, configFile = templateConfigXmlPath) {
     const configXml = new ConfigParser(configFile);
 
-    await create.createProject(tmpDir, packageName, projectName, {}, configXml)
-        .then(() => verifyProjectFiles(tmpDir, projectName))
+    await create.createProject(tmpDir, packageName, projectName, { link }, configXml)
+        .then(() => verifyProjectFiles(tmpDir, projectName, link))
         .then(() => verifyProjectBundleIdentifier(tmpDir, projectName, packageName));
 }
 
@@ -135,12 +140,18 @@ describe('create', () => {
         return verifyCreatedProject(tmpDir, packageName, projectName);
     });
 
+    it('should create project with linked CordovaLib', () => {
+        const packageName = 'com.test.app3';
+        const projectName = 'testcreatelink';
+        return verifyCreatedProject(tmpDir, packageName, projectName, true);
+    });
+
     it('should copy config.xml into the newly created project', () => {
         const configPath = path.join(__dirname, 'fixtures', 'test-config-3.xml');
         const packageName = 'io.cordova.hellocordova.ios';
         const projectName = 'Hello Cordova';
 
-        return verifyCreatedProject(tmpDir, packageName, projectName, configPath)
+        return verifyCreatedProject(tmpDir, packageName, projectName, false, configPath)
             .then(() => verifyProjectDeploymentTarget(tmpDir, '15.0'));
     });
 });