Minimal and backend-only Maven projects, default from 7.0.275

.github/workflows/archetype-smoke.yml

@@ -24,6 +24,9 @@ on:
       - 'maven/backend/**'
       - 'maven/integration-tests/cn1app-archetype-test.sh'
       - 'maven/integration-tests/cn1app-staged-jar-test.sh'
+      - 'maven/integration-tests/cn1app-minimal-layout-test.sh'
+      - 'scripts/initializr/common/src/main/resources/common-hosted-platform-profiles.xml'
+      - 'scripts/initializr/common/src/main/resources/backend-only-pom.xml'
       # What a generated project stages for upload also depends on the
       # dependency versions and aggregators the archetype pulls in.
       - 'maven/pom.xml'
@@ -46,6 +49,9 @@ on:
       - 'maven/backend/**'
       - 'maven/integration-tests/cn1app-archetype-test.sh'
       - 'maven/integration-tests/cn1app-staged-jar-test.sh'
+      - 'maven/integration-tests/cn1app-minimal-layout-test.sh'
+      - 'scripts/initializr/common/src/main/resources/common-hosted-platform-profiles.xml'
+      - 'scripts/initializr/common/src/main/resources/backend-only-pom.xml'
       # What a generated project stages for upload also depends on the
       # dependency versions and aggregators the archetype pulls in.
       - 'maven/pom.xml'
@@ -131,3 +137,12 @@ jobs:
           cd maven/integration-tests
           # The project's CSS compile opens an AWT frame, so it needs a display.
           xvfb-run -a bash cn1app-staged-jar-test.sh
+      # The archetype's default layouts: an app with no platform modules, whose
+      # common module builds, tests and stages every platform, and a backend-only
+      # project. Nothing is submitted and the simulator is never launched.
+      - name: Build the minimal and backend-only layouts
+        env:
+          CN1_BACKEND_PACKAGE_REQUIRED: '1'
+        run: |
+          cd maven/integration-tests
+          xvfb-run -a bash cn1app-minimal-layout-test.sh

.github/workflows/scaffolding-parity.yml

@@ -24,6 +24,7 @@ on:
       - 'maven/cn1app-archetype/src/main/resources/archetype-resources/pom.xml'
       - 'maven/cn1lib-archetype/src/main/resources/archetype-resources/pom.xml'
       - 'scripts/initializr/common/src/main/resources/common.zip'
+      - 'scripts/initializr/common/src/main/resources/backend-only-pom.xml'
       - 'maven/integration-tests/scaffolding-settings-parity-test.sh'
       - 'maven/integration-tests/normalize_cn1_settings.py'
       - 'maven/integration-tests/validate_initializr_pom_coordinates.py'
@@ -36,6 +37,7 @@ on:
       - 'maven/cn1app-archetype/src/main/resources/archetype-resources/pom.xml'
       - 'maven/cn1lib-archetype/src/main/resources/archetype-resources/pom.xml'
       - 'scripts/initializr/common/src/main/resources/common.zip'
+      - 'scripts/initializr/common/src/main/resources/backend-only-pom.xml'
       - 'maven/integration-tests/scaffolding-settings-parity-test.sh'
       - 'maven/integration-tests/normalize_cn1_settings.py'
       - 'maven/integration-tests/validate_initializr_pom_coordinates.py'

docs/developer-guide/Advanced-Topics-Under-The-Hood.asciidoc

@@ -409,6 +409,8 @@ The implementation of this interface is identical for Android (Java/Kotlin) & Ja
 For iOS native interfaces you can implement the generated `...Impl` class in Objective-C _or_ Swift. +
 For Android native interfaces you can implement the generated `...Impl` class in Java _or_ Kotlin.
 
+In a Maven project the directories below hold the native code whether the project has a module for that platform or not. `mvn cn1:generate-native-interfaces` creates them as needed, and a project without the platform's module builds them from the `common` module (see <<maven-minimal-layout>>).
+
 [cols="1,3,3",options="header"]
 |===
 | Platform

docs/developer-guide/Backend.asciidoc

@@ -73,20 +73,21 @@ a server and go into depth:
 
 === A first server
 
-The archetype and the initializr both generate a `backend` module beside the
-client ones:
+The archetype (with `-DprojectType=app-with-backend`) and the initializr (with the
+_App with backend_ project type) both generate a `backend` module beside the app:
 
 ----
 myapp/
   common/    shared app code
-  javase/    desktop build
-  ios/       iOS build
-  android/   Android build
   backend/   the server
     pom.xml
     src/main/java/com/example/myapp/Notes.java
 ----
 
+A server-only project, generated with `-DprojectType=backend-only` or the
+initializr's _Backend only_ type, has no `common` module: the server is the whole
+project, at the root (see <<maven-backend-only>>).
+
 A server is a class with routes on it. The annotations are Spring's, under
 Codename One's package names, so this reads the same way to anyone who has
 written a Spring controller:
@@ -124,6 +125,9 @@ mvn -pl backend -Dcodename1.platform=backend cn1:backend           # run it on t
 mvn -pl backend -Dcodename1.platform=backend cn1:backend-package   # build the native binary
 ----
 
+In a backend-only Maven project, run `./mvnw cn1:backend` and
+`./mvnw cn1:backend-package` from the root, with no module or property.
+
 In a Gradle project the backend is the `backend` subproject (or the whole project,
 for a backend-only application), and the same two steps are tasks:
 

docs/developer-guide/Maven-Appendix-Archetypes.adoc

@@ -4,7 +4,34 @@
 [#cn1app-archetype]
 === Codename One application project archetype (cn1app-archetype)
 
-The `cn1app-archetype` is the basis for all maven Codename One application projects. It provides a multimodule project with the following modules:
+The `cn1app-archetype` is the basis for all Maven Codename One application projects. Two properties choose the shape of the project it generates:
+
+`platformModules`::
+The platform modules to generate. The default, `none`, is the minimal layout: the root `pom.xml` and the `common` module, and nothing else. `all` generates a module for each platform (`javase`, `android`, `ios`, `javascript`, `win` and `linux`), and a comma-separated list such as `javase,android` generates just those.
+
+`projectType`::
+`app` (the default), `app-with-backend`, which adds the `backend` module (see <<_server_side_backend,the backend chapter>>), or `backend-only`, which generates a server on its own: a single module at the root with no application.
+
+`-DplatformModules=all -DprojectType=app-with-backend` generates the full multi-module layout.
+
+[#maven-minimal-layout]
+==== Projects without platform modules
+
+The platform modules are optional. When a platform has no module, the `common` module builds it: `./build.sh android` and `mvn package -Dcodename1.platform=android` work the same with or without an `android` module, and so do the simulator, the desktop app and the unit tests. A platform has a module of its own exactly when `<platform>/pom.xml` exists, so you can add one later, for example to give that platform its own build plugins or dependencies, and from then on the module builds that platform instead of `common`.
+
+Native interface implementations live in the same directories either way. `mvn cn1:generate-native-interfaces` creates `android/src/main/java`, `ios/src/main/objectivec`, `javase/src/main/java` and the others as needed, without a `pom.xml`, and the build picks them up from there. The Java SE implementations are compiled into `common/target/cn1-javase/classes`, apart from the application's own classes, so they never reach a device build.
+
+A project without a `javase` module keeps the desktop app's native theme in `common/src/desktop/resources`. `mvn package -Pexecutable-jar -Dcodename1.platform=javase` writes the desktop jar to `common/target`.
+
+[#maven-backend-only]
+==== Backend-only projects
+
+A project generated with `-DprojectType=backend-only` is a server and nothing else: a `pom.xml`, `application.properties` and the sources under `src/main/java`, all at the root. The commands drop the module and the profile:
+
+----
+./mvnw cn1:backend           # run it on this JVM
+./mvnw cn1:backend-package   # build the native binary
+----
 
 See https://shannah.github.io/cn1-maven-archetypes/cn1app-archetype-tutorial/getting-started.html[Getting Started with the Bare-Bones Java App Template] for details on using this archetype.
 

docs/developer-guide/Maven-Getting-Started.adoc

@@ -252,7 +252,7 @@ With Codename One projects, there are a few caveats (see <<compliance-check>>),
 ==== Which `pom.xml` to add the `<dependency>` snippet to
 
 Suppose you have a Maven `<dependency>` snippet that you've copied from Maven central, and it's burning a hole in your clipboard while you're trying to figure out where to paste it into your project.
-Codename One application projects, being multi-module projects, have more than one `pom.xml` file; One per module.
+Codename One application projects are multi-module projects, so they have more than one `pom.xml` file: the root one, the `common` module's, and one per platform module the project has. A project generated with the defaults has no platform modules (see <<maven-minimal-layout>>).
 
 **Question:** Which pom.xml file should you paste the snippet into?
 
@@ -274,14 +274,16 @@ Here's an overview:
 %PROJECT_ROOT%/pom.xml::
 The root pom.xml file is the parent module of all other modules. Anything you add here will be inherited by all the modules. It can be helpful to use `<dependencyManagement>` and `<pluginManagement>` sections in this file to merge versions for dependencies and plugins project-wide. This is also a good place to add project meta-data like `<developers>`, `<scm>`.
 
-Java SE/pom.xml::
+javase/pom.xml (when the project has a javase module)::
 Any dependencies that are only required for native implementations on the Java SE platform can be added here. Dependencies added to this project aren't subject to <<compliance-check, the compliance check>>.
 +
 Additionally, this module handles the build toolchain for the Java SE platform. This includes Mac and Windows Desktop builds, as well as Java SE desktop builds. If you want to customize the build workflow for any of these targets, you would do so by adding plugin executions in this pom.xml file.
 
-android, ios, win, and JavaScript::
+android, ios, win, linux, and javascript (when the project has them)::
 These modules don't use Maven for their dependencies (Android may deserve a small asterisk here, but that's complicated), so the primary thing you'd want to *change* in these pom.xml files are the build toolchain for those targets. For example, you might add plugin executions for your CI workflow on builds targeting these particular platforms.
 
+A project without these modules builds every platform from the common module. To customize one platform's build, add its module: a `<platform>/pom.xml` copied from a project generated with `-DplatformModules=all`. The common module stops building that platform as soon as the module exists.
+
 ****
 
 [#maven-dependency-example]

maven/cn1app-archetype/pom.xml

@@ -122,6 +122,47 @@
                 <copy file="${project.basedir}/../../scripts/initializr/common/src/main/resources/agent-skill-claude-stub.md"
                       tofile="${project.build.outputDirectory}/archetype-resources/.claude/skills/codename-one/SKILL.md"
                       overwrite="true"/>
+                <!-- common/pom.xml carries the profiles that let common build any
+                     platform the project has no module for. The initializr injects the
+                     same file into its own templates, so both generators ship one copy. -->
+                <copy file="${project.basedir}/../../scripts/initializr/common/src/main/resources/backend-only-pom.xml"
+                      todir="${project.build.outputDirectory}/archetype-resources/.cn1-backend-only"
+                      overwrite="true"/>
+                <copy todir="${project.build.outputDirectory}/archetype-resources/.cn1-backend-only" overwrite="true">
+                  <fileset dir="${project.basedir}/../build-engine/src/main/resources/com/codename1/project/templates/gradle/backend"
+                           includes="Api.java.txt,Greeter.java.txt,application.properties.txt,application-dev.properties.txt"/>
+                </copy>
+                <loadfile property="cn1.hostedPlatformProfiles"
+                          srcFile="${project.basedir}/../../scripts/initializr/common/src/main/resources/common-hosted-platform-profiles.xml"
+                          encoding="UTF-8"/>
+                <!-- From the source every time: an incremental build does not copy the
+                     resource again, and the copy in target has lost its marker. A filtered
+                     copy, not <replace>: that task rewrites through a temp file, which Ant
+                     creates owner-only (0600), and an unreadable pom.xml in the workspace
+                     fails every later hashFiles('**/pom.xml') on CI. -->
+                <!-- Deleted first: a copy over an existing file keeps that file's mode. -->
+                <delete file="${project.build.outputDirectory}/archetype-resources/common/pom.xml"/>
+                <copy file="${project.basedir}/src/main/resources/archetype-resources/common/pom.xml"
+                      tofile="${project.build.outputDirectory}/archetype-resources/common/pom.xml"
+                      overwrite="true" encoding="UTF-8">
+                  <filterchain>
+                    <tokenfilter>
+                      <replacestring from="        &lt;!-- @CN1_HOSTED_PLATFORM_PROFILES@ --&gt;"
+                                     to="${cn1.hostedPlatformProfiles}"/>
+                    </tokenfilter>
+                  </filterchain>
+                </copy>
+                <loadfile property="cn1.hostedPlatformProfilesMarker"
+                          srcFile="${project.build.outputDirectory}/archetype-resources/common/pom.xml"
+                          encoding="UTF-8">
+                  <filterchain>
+                    <linecontains>
+                      <contains value="@CN1_HOSTED_PLATFORM_PROFILES@"/>
+                    </linecontains>
+                  </filterchain>
+                </loadfile>
+                <fail if="cn1.hostedPlatformProfilesMarker"
+                      message="common/pom.xml still carries the hosted platform profiles marker"/>
               </target>
             </configuration>
           </execution>