diff --git a/docs/TODO.md b/docs/TODO.md index a44603c629..5cd771123b 100644 --- a/docs/TODO.md +++ b/docs/TODO.md @@ -10,6 +10,7 @@ ## Tooling & Build Flow Modernization - [ ] Rewrite `Working-With-CodenameOne-Sources.asciidoc` around the Maven multi-module build in `/maven`, including local test commands, dependency management tips, and how our GitHub Actions replace the old Ant targets for CI.【F:docs/developer-guide/Working-With-CodenameOne-Sources.asciidoc†L1-L85】【F:maven/README.adoc†L1-L68】 +- [ ] Rework `Working-With-CodenameOne-Sources.asciidoc` to fold in the Maven project workflow guidance now embedded in the developer guide and eliminate duplicated setup steps between the chapters.【F:docs/developer-guide/Working-With-CodenameOne-Sources.asciidoc†L1-L85】【F:docs/developer-guide/Maven-Project-Workflow.asciidoc†L1-L14】 - [ ] Retire or substantially revise `Travis-CI-Integration.asciidoc` to highlight our current CI guidance (GitHub Actions templates, self-hosted options) and archive Travis-specific screenshots and steps.【F:docs/developer-guide/Travis-CI-Integration.asciidoc†L1-L112】 - [ ] Update the Designer/tooling coverage in `basics.asciidoc` so it walks through launching the modern Designer distribution from Maven projects without relying on `designer_1.jar` shell commands.【F:docs/developer-guide/basics.asciidoc†L1050-L1070】 - [ ] Rebuild `Working-With-The-GUI-Builder.asciidoc` around the current GUI Builder experience (with Java 11+ support, IntelliJ/VScode integration), moving legacy troubleshooting for `guibuilder_1.jar` into an appendix or "legacy" callout.【F:docs/developer-guide/Working-With-The-GUI-Builder.asciidoc†L1-L126】 diff --git a/docs/developer-guide/Advanced-Topics-Under-The-Hood.asciidoc b/docs/developer-guide/Advanced-Topics-Under-The-Hood.asciidoc index b9560bb9fe..f09dc49bff 100644 --- a/docs/developer-guide/Advanced-Topics-Under-The-Hood.asciidoc +++ b/docs/developer-guide/Advanced-Topics-Under-The-Hood.asciidoc @@ -28,9 +28,6 @@ Here is the current list of supported arguments, notice that build hints are add |android.installLocation |Maps to android:installLocation manifest entry defaults to auto. Can also be set to internalOnly or preferExternal. -|android.gradle -|Deprecated, this mode is no longer supported. true/false defaults to false prior to 3.3 and true after. Uses Gradle instead of Ant to build the Android app - |android.xapplication |defaults to an empty string. Allows developers of native Android code to add text within the application block to define things such as widgets, services etc. @@ -88,7 +85,7 @@ Here is the current list of supported arguments, notice that build hints are add |*Deprecated, please android.playService.+++*+++!* Indicates whether Goolge Play Services should be included into the build, defaults to false but that might change based on the functionality of the application and other build hints. Adding Google Play Services support allows us to use a more refined location implementation and invoke some Google specific functionality from native code. |android.playService.plus, android.playService.auth, android.playService.base, android.playService.identity, android.playService.indexing, android.playService.appInvite, android.playService.analytics, android.playService.cast, android.playService.gcm, android.playService.drive, android.playService.fitness, android.playService.location, android.playService.maps, android.playService.ads, android.playService.vision, android.playService.nearby, android.playService.panorama, android.playService.games, android.playService.safetynet, android.playService.wallet, android.playService.wearable -|Allows including only a specific play services library portion. Notice that this setting conflicts with the deprecated `android.includeGPlayServices` and only works with the gradle build (which is on by default but can be toggled using `android.gradle`). + +|Allows including only a specific play services library portion. Notice that this setting conflicts with the deprecated `android.includeGPlayServices` and only works with the Gradle-based Android build pipeline. + If none of the services are defined to true then plus, auth, base, analytics, gcm, location, maps & ads will be set to true. If one or more of the `android.playService` entries are defined to something then all entries will default to false. @@ -2156,43 +2153,6 @@ In the drop target you can override the following methods: -=== Continuous Integration & Release Engineering - -Codename One was essentially built for continuous integration since the build servers are effectively a building block for such an architecture. However, there are several problems with that: the first of which is limited server capacity. - -If all users would start sending builds with every commit the servers would instantly become unusable due to the heavy load. To circumvent this CI support is limited only on the Enterprise level which allows Codename One to stock more servers and cope with the rise in demand related to the feature. - -To integrate with any CI solution just use the standard Ant targets such as `build-for-android-device`, `build-for-iphone-device` etc. - -Normally, this would be a problem since the build is sent but since it isn't blocking you wouldn't get the build result and wouldn't be able to determine if the build passed or failed. To enable this just edit the build XML and add the attribute `automated="true"` to the codeNameOne tag in the appropriate -targets. - -This will deliver a `result.zip` file under the `dist` folder containing the binaries of a successful build. It will -also block until the build is completed. This should be pretty easy to integrate with any CI system together with -our automated testing solutions . - -E.g. we can do a synchronous build like this: - -[source,xml] ----- - - - ----- - -This allows us to build a JavaScript version of the app automatically as part of a release build script. - === Android Lollipop ActionBar Customization When running on Android Lollipop (5.0 or newer) the native action bar will use the Lollipop design. This isn't applicable diff --git a/docs/developer-guide/Index.asciidoc b/docs/developer-guide/Index.asciidoc index 31526b33f9..d3131d0479 100644 --- a/docs/developer-guide/Index.asciidoc +++ b/docs/developer-guide/Index.asciidoc @@ -248,13 +248,13 @@ Import the generated Maven project into your preferred IDE and use the Codename * *Eclipse* – use *File > Import > Existing Maven Projects*, then use the Codename One launch shortcuts provided by the plugin for simulator and build tasks. * *Command line* – invoke Maven goals directly whenever you need to integrate with CI/CD pipelines or scripting. -For deeper coverage of the Maven goals and project structure, see the https://shannah.github.io/codenameone-maven-manual/[Codename One Maven Manual]. +For deeper coverage of the Maven goals, project structure, and automation tasks, continue with <>. NOTE: Arbitrary Maven dependencies probably won't work for Codename One. Many dependencies assume a full JDK which Codename One can't provide and they often assume functionality that might not be available e.g. reflection, Spring, etc. .Legacy onboarding resources **** -The retired Ant-based IDE plugins for NetBeans, Eclipse and IntelliJ IDEA – together with the simulator screenshots from those workflows – are still available in the legacy documentation for teams maintaining older projects. New projects should follow the Maven-based instructions above. +Legacy Ant-based project instructions remain available for teams maintaining older codebases. New projects should follow the Maven workflows described in this guide. **** ==== Important Notes for New Projects diff --git a/docs/developer-guide/codenameone-maven-manual/appendix_api.adoc b/docs/developer-guide/Maven-Appendix-API.adoc similarity index 100% rename from docs/developer-guide/codenameone-maven-manual/appendix_api.adoc rename to docs/developer-guide/Maven-Appendix-API.adoc diff --git a/docs/developer-guide/codenameone-maven-manual/appendix_archetypes.adoc b/docs/developer-guide/Maven-Appendix-Archetypes.adoc similarity index 100% rename from docs/developer-guide/codenameone-maven-manual/appendix_archetypes.adoc rename to docs/developer-guide/Maven-Appendix-Archetypes.adoc diff --git a/docs/developer-guide/codenameone-maven-manual/appendix_control_center.adoc b/docs/developer-guide/Maven-Appendix-Control-Center.adoc similarity index 69% rename from docs/developer-guide/codenameone-maven-manual/appendix_control_center.adoc rename to docs/developer-guide/Maven-Appendix-Control-Center.adoc index adaedbf18e..23f51f6849 100644 --- a/docs/developer-guide/codenameone-maven-manual/appendix_control_center.adoc +++ b/docs/developer-guide/Maven-Appendix-Control-Center.adoc @@ -8,9 +8,6 @@ The Codename One Settings app (aka Codename One Preferences, aka Control Center) === Opening Codename One Settings ==== Opening Codename One Settings from Command-line -++++ - -++++ Use the `run.sh` (or run.bat, if on Windows) to open Codename One settings: @@ -20,36 +17,27 @@ Use the `run.sh` (or run.bat, if on Windows) to open Codename One settings: ---- ==== Opening Codename One Settings from IntelliJ -++++ - -++++ Click on the "Configuration" menu in the upper right of the toolbar, and select "Tools" > "Codename One Settings" as shown below. -image::images/intellij-open-settings.png[] +image::img/intellij-open-settings.png[] ==== Opening Codename One Settings from NetBeans -++++ - -++++ Right-click on the project in the project inspector, and select "Maven" > "Open Control Center" as shown below: -image::images/netbeans-open-control-center.png[] +image::img/netbeans-open-control-center.png[] ==== Opening Codename One Settings from Eclipse -++++ - -++++ -Press the image:images/eclipse-run-as-button.png[] button, and select the "_My Project_ Settings" option. (Where _My Project_ is the name of your project). E.g. +Press the image:img/eclipse-run-as-button.png[] button, and select the "_My Project_ Settings" option. (Where _My Project_ is the name of your project). E.g. -image:images/eclipse-open-settings.png[] +image:img/eclipse-open-settings.png[] [#dashboard] === The Dashboard Once inside Codename One Settings, you'll see a dashboard like the following: -image::images/control-center-dashboard.png[] +image::img/control-center-dashboard.png[] diff --git a/docs/developer-guide/codenameone-maven-manual/appendix_goals.adoc b/docs/developer-guide/Maven-Appendix-Goals.adoc similarity index 100% rename from docs/developer-guide/codenameone-maven-manual/appendix_goals.adoc rename to docs/developer-guide/Maven-Appendix-Goals.adoc diff --git a/docs/developer-guide/codenameone-maven-manual/appendix_rich_properties_file.adoc b/docs/developer-guide/Maven-Appendix-Rich-Properties.adoc similarity index 100% rename from docs/developer-guide/codenameone-maven-manual/appendix_rich_properties_file.adoc rename to docs/developer-guide/Maven-Appendix-Rich-Properties.adoc diff --git a/docs/developer-guide/codenameone-maven-manual/creating-cn1libs.adoc b/docs/developer-guide/Maven-Creating-CN1Libs.adoc similarity index 89% rename from docs/developer-guide/codenameone-maven-manual/creating-cn1libs.adoc rename to docs/developer-guide/Maven-Creating-CN1Libs.adoc index 2a0487e240..32e8b291f3 100644 --- a/docs/developer-guide/codenameone-maven-manual/creating-cn1libs.adoc +++ b/docs/developer-guide/Maven-Creating-CN1Libs.adoc @@ -29,10 +29,7 @@ TIP: Codename One supports a subset of JavaSE8, as well as addition APIs for acc Use the `cn1lib-archetype` for generating a new Codename One library project as follows: -==== CLI -++++ - -++++ +==== Command Line [source,bash] ---- @@ -74,64 +71,58 @@ And follow the prompts. This will, result in fewer prompts because you have alr This will create a new project for you in the current directory, in a newly created directory named after the `artifactId` that you entered. -==== IntelliJ -++++ - -++++ +==== IntelliJ IDEA . Select "File" > "New Project"... + -image::images/intellij-new-project-menu.png[] +image::img/intellij-new-project-menu.png[] . Select "Maven" in the left menu. + -image::images/intellij-new-project-dialog-maven.png[] -. Check the "Create from Archetype" checkbox. image:images/intellij-create-from-archetype-checkbox.png[]. This should allow you to choose from of archetypes that are already known to IntelliJ. +image::img/intellij-new-project-dialog-maven.png[] +. Check the "Create from Archetype" checkbox. image:img/intellij-create-from-archetype-checkbox.png[]. This should allow you to choose from of archetypes that are already known to IntelliJ. . If you don't see an option for "com.codenameone:cn1lib-archetype", then IntelliJ doesn't know about it yet. If, however you *do* see this option, you can skip to the next step. Press the "Add Archetype..." button. This will display a dialog for you to enter the details of the archetype. + -image::images/intellij-add-archetype.png[] +image::img/intellij-add-archetype.png[] + Fill in this dialog as shown in the above image. Specifically `groupId`="com.codenameone", `artifactId`="cn1lib-archetype", and `version`="LATEST" + Then press "OK". . Select the option that says "com.codenameone:cn1lib-archetype" + -image::images/intellij-select-cn1lib-archetype.png[] +image::img/intellij-select-cn1lib-archetype.png[] + Then press "Next" . This will display a form where you can enter the details of your project such as its location (where you want to create the project folder), the name, the artifact ID, and the groupID. Fill in this form as you see fit. + -image::images/intellij-new-cn1lib-project-details-form.png[] +image::img/intellij-new-cn1lib-project-details-form.png[] + Then click "Next" . The final form in this wizard summarizes the project details and gives you an opportunity to add additional properties to pass to the `archetype:generate` goal. In our case we don't need to add any additional properties. If the information looks correct, you can just press "Next". + -image::images/intellij-new-cn1lib-project-details-summary.png[] +image::img/intellij-new-cn1lib-project-details-summary.png[] At this point you will be prompted to open the project. ==== NetBeans -++++ - -++++ . Select "File" > "New Project..." + -image::images/netbeans-new-project-menu.png[] +image::img/netbeans-new-project-menu.png[] . In the "New Project" dialog, select "Java with Maven" in the left panel, and "Project from Archetype" in the right panel, as shown below. + -image::images/netbeans-new-project-maven-dialog.png[] +image::img/netbeans-new-project-maven-dialog.png[] + Then press "Next" . This will bring you to the "Maven Archetype" dialog as shown below: + -image::images/netbeans-maven-archetype-cn1lib-dialog.png[] +image::img/netbeans-maven-archetype-cn1lib-dialog.png[] + Enter "com.codenameone" or "cn1lib-archetype" into the search field. Then select "cn1lib-archetype" in the "Known archetypes:" panel. This will prefill the *Group ID*, *Artifact ID* and *Version* fields for you. You may want to change *Version* to LATEST to ensure that it tries to use the latest available version of the archetype. + Then click "Next" . This will bring you to the "Name and Location" panel of the wizard. + -image::images/netbeans-new-project-name-and-location.png[] +image::img/netbeans-new-project-name-and-location.png[] + Enter in the project name (which you'll be forced to use as the artifact ID also), project location, groupId, version, and package. The "Package" is unimportant here as it isn't used anywhere in the project. @@ -140,28 +131,25 @@ Once you have entered the information to your liking press the "Finish" button. This will create a new libary project for you at the location you specified. -==== Eclipse -++++ - -++++ +==== Eclipse IDE . Select "File" > "New Project..." . In the _New Project_ dialog, expand the _Maven_ item, and select _Maven Project_ + -image::images/eclipse-new-project-wizard.png[] +image::img/eclipse-new-project-wizard.png[] + Then press "Next" . The next panel will look like the below image. The default settings on this panel should be fine. Press _Next_ + -image::images/eclipse-new-project-wizard-new-maven-project.png[] +image::img/eclipse-new-project-wizard-new-maven-project.png[] . In the next panel, enter "cn1lib" in the _Filter_ field. After a moment the _cn1lib-archetype_ should appear in the area below as shown here: + -image::images/eclipse-new-maven-project-cn1lib.png[] +image::img/eclipse-new-maven-project-cn1lib.png[] + Select that option, and press _Next_ . The next panel, allows you to enter your project details, such as group ID, and artifact ID. Your project information here and then press _Finish_. + -image:images/eclipse-new-maven-project-details.png[] +image:img/eclipse-new-maven-project-details.png[] This will create a new libary project for you at the location you specified. @@ -185,61 +173,49 @@ tests:: An application project for writing unit tests against your library. This module is in the "tests" directory of the main project. -===== IntelliJ -++++ - -++++ +===== IntelliJ IDEA IDEA The project inspector will look like: -image::images/intellij-myfirstlib-project-inspector.png[] +image::img/intellij-myfirstlib-project-inspector.png[] This top-level view of the module structure may seem daunting. Most of your development will occur inside the "common" module. If we expand that module it will look more familiar to developers who have used the old Ant project structure: -image::images/intellij-myfirstlibrary-common-project-files.png[] +image::img/intellij-myfirstlibrary-common-project-files.png[] Your cross-platform Java source would go in the `common/src/main/java` directory. Your CSS files go in the `common/src/main/css` directory. ===== NetBeans -++++ - -++++ The project inspector will look like: -image::images/netbeans-myfirstlibrary-project-inspector.png[] +image::img/netbeans-myfirstlibrary-project-inspector.png[] This top-level view of the modules doesn't provide a clear view of the project landscape, however, since 99% of your development will occur inside the `common` submodule. Let's open that "common" sub-module project as well and take a peek. Right click on the "Common" sub-module, and select "Open Project" as shown below: -image::images/netbeans-myfirstlibrary-open-common-submodule.png[] +image::img/netbeans-myfirstlibrary-open-common-submodule.png[] With the common subproject open, the project inspector will look like: -image::images/netbeans-myfirstlibrary-project-inspector-with-common.png[] +image::img/netbeans-myfirstlibrary-project-inspector-with-common.png[] In this screenshot I have expanded "Source Packages" and "Other Sources/css" to highlight where your Java source files and CSS source files will be located. The project inspector hides a few important files, however, so here is a screenshot of the File inspector for the common project: -image::images/netbeans-my-first-library-file-inspector-common.png[] +image::img/netbeans-my-first-library-file-inspector-common.png[] -===== Eclipse -++++ - -++++ +===== Eclipse IDE IDE The package explorer will look like: -image::images/eclipse-cn1lib-package-explorer.png[] +image::img/eclipse-cn1lib-package-explorer.png[] In this screenshot, I have expanded the _common/src/main/css_ and _common/src/main/java_ directories as this is where most of your module source will go. -===== CLI -++++ - -++++ +===== Command Line If we do a file listing on the project directory, it shows the following: @@ -375,10 +351,7 @@ Other non-java resources that you want to have included in the classpath. [#building-library] ==== Building the Library -===== CLI -++++ - -++++ +===== Command Line To build the library, simply run the "install" goal on the root module as follows: @@ -387,34 +360,25 @@ To build the library, simply run the "install" goal on the root module as follow mvn install ---- -===== IntelliJ -++++ - -++++ +===== IntelliJ IDEA IDEA -Press the "build" image:images/intellij-build-icon.png[] button on the toolbar. +Press the "build" image:img/intellij-build-icon.png[] button on the toolbar. ===== NetBeans -++++ - -++++ Right click on the "root" module in the project explorer and select "Build". -image::images/netbeans-right-click-build.png[] +image::img/netbeans-right-click-build.png[] IMPORTANT: You must build the root module and not one of the submodules. -Alternatively you could have just selected the "root" module in the project explorer and pressed the "build" image:images/netbeans-build-button.png[] button on the toolbar. +Alternatively you could have just selected the "root" module in the project explorer and pressed the "build" image:img/netbeans-build-button.png[] button on the toolbar. -===== Eclipse -++++ - -++++ +===== Eclipse IDE IDE Right click on the "root" module in the project explorer and select _Run as_ > _Maven Install_ -image::images/eclipse-build-cn1lib.png[] +image::img/eclipse-build-cn1lib.png[] TIP: If the build fails for any reason, check to make sure that your project is using the latest version of the Codename One plugin. You can do this by opening the _pom.xml_ file, and changing the `cn1.version` and `cn1.plugin.version` properties to reference the latest version. Check for the latest version https://search.maven.org/artifact/com.codenameone/codenameone[here]. diff --git a/docs/developer-guide/codenameone-maven-manual/getting-started.adoc b/docs/developer-guide/Maven-Getting-Started.adoc similarity index 95% rename from docs/developer-guide/codenameone-maven-manual/getting-started.adoc rename to docs/developer-guide/Maven-Getting-Started.adoc index 2937773a6f..b36fb39f09 100644 --- a/docs/developer-guide/codenameone-maven-manual/getting-started.adoc +++ b/docs/developer-guide/Maven-Getting-Started.adoc @@ -7,7 +7,7 @@ The easiest way to create a new project is to use the https://start.codenameone.com[Codename One initializr]. -image::images/codenameone-initializr-screenshot.png[] +image::img/codenameone-initializr-screenshot.png[] This tool will allow you to choose from a growing selection of project templates, and download a starter project that you can open in your preferred IDE (IntelliJ IDEA, NetBeans, etc..), or build directly on the command-line using Maven. @@ -135,10 +135,7 @@ This will generate the new project in the current directory inside a folder name After building the project, try running it to make sure that the migration worked. E.g. Assuming that your artifactId was myapp: -==== CLI -++++ - -++++ +==== Command Line [source,bash] ---- @@ -150,46 +147,37 @@ NOTE: On Windows it would be `run.bat` instead of `run.sh`. If All goes well, your app should open in the Codename One simulator. -==== IntelliJ -++++ - -++++ +==== IntelliJ IDEA -Open the `myapp` folder in IntelliJ. Then press the "Run" image:images/intellij-run-icon.png[] button in the upper right of the toolbar. +Open the `myapp` folder in IntelliJ. Then press the "Run" image:img/intellij-run-icon.png[] button in the upper right of the toolbar. If All goes well, your app should open in the Codename One simulator. ==== NetBeans -++++ - -++++ IMPORTANT: Before opening the project in NetBeans, be sure to copy the files in the _tools/netbeans_ directory into the root directory. These are necessary for NetBeans to properly run, build, and debug the project. -Open the `myapp` folder as a project in NetBeans. Then press the "Run" image:images/netbeans-run-icon.png[] button on the toolbar. +Open the `myapp` folder as a project in NetBeans. Then press the "Run" image:img/netbeans-run-icon.png[] button on the toolbar. If all goes well it should open in the Codename One simulator. -==== Eclipse -++++ - -++++ +==== Eclipse IDE Open Eclipse, and select "File" > "Import.." -image::images/eclipse-file-menu-import.png[] +image::img/eclipse-file-menu-import.png[] In the _Import_ dialog, expand _Maven_, select _Existing Maven Projects_, and press _Next_. -image::images/eclipse-import-dialog.png[] +image::img/eclipse-import-dialog.png[] In the next panel, press the _Browse_ button, and, in the file dialog, select the "myapp" directory, and press _Next_. -image::images/eclipse-import-browse-dialog.png[] +image::img/eclipse-import-browse-dialog.png[] The next panel should look similar to the one below. Make sure all of the projects are "checked", and press _Finish_. -image::images/eclipse-import-list-projects-dialog.png[] +image::img/eclipse-import-list-projects-dialog.png[] **Almost there, but not quite...** @@ -197,19 +185,19 @@ Next we need to import the Eclipse launch configurations located inside the _too Select _File_ > _Import..._ again, but this time, in the _Import_ dialog, select _Run/Debug_ > _Launch Configurations_ and click _Next_. -image::images/eclipse-import-launch-configurations-dialog.png[] +image::img/eclipse-import-launch-configurations-dialog.png[] In the next panel, press _Browse..._ then select the _tools/eclipse_ directory. -image::images/eclipse-launch-configurations-file-dialog.png[] +image::img/eclipse-launch-configurations-file-dialog.png[] Then check the _eclipse_ option, and press _Finish_ -image::images/eclipse-import-launch-configurations-finish.png[] +image::img/eclipse-import-launch-configurations-finish.png[] The "Run" button menu should now include options for all of the major build targets. You can see them by pressing on the _Run_ button in the toolbar: -image::images/eclipse-run-button-dropdown.png[] +image::img/eclipse-run-button-dropdown.png[] Select the _MyApp - Run Simulator_ option from this menu. @@ -348,17 +336,17 @@ As I mention throughout this guide, the best place to find and install add-ons f From the dashboard, select "Advanced Settings" > "Extensions" in the navigation menu on the left as shown below: -image::images/image-2021-03-08-06-57-26-835.png[Control center navigation menu] +image::img/image-2021-03-08-06-57-26-835.png[Control center navigation menu] This will bring up a list of available Codename One extensions as shown below: -image::images/control-center-extensions.png[Control center extensions page] +image::img/control-center-extensions.png[Control center extensions page] As an example, let's install the "Google Maps" library. Type in "Maps" into the search box, and it should narrow the options down to three libraries as shown below: -image:images/control-center-extensions-search-maps.png[Control Center Extensions filtered on maps] +image:img/control-center-extensions-search-maps.png[Control Center Extensions filtered on maps] The one in the middle "Codename One Google Native", is the Google maps lib that we want. diff --git a/docs/developer-guide/Maven-Introduction.adoc b/docs/developer-guide/Maven-Introduction.adoc new file mode 100644 index 0000000000..4ca0a1220d --- /dev/null +++ b/docs/developer-guide/Maven-Introduction.adoc @@ -0,0 +1,14 @@ +== Introduction + +Codename One uses Maven as its primary build tool. This guide aims to be the definitive source of information for this project structure. + +=== Conventions + +The instructions throughout this chapter provide parallel guidance for the supported development environments. Each subsection heading clearly identifies the target tooling so you can follow the directions that match your workflow: + +* **Command Line (CLI)** – Focused on running Maven from a terminal. The commands use a Unix-style shell syntax; adapt the examples for Windows when necessary. +* **IntelliJ IDEA** – Step-by-step directions for working inside IntelliJ. +* **NetBeans** – Equivalent instructions tailored to NetBeans. +* **Eclipse** – Maven-based guidance for Eclipse users. + +When you encounter environment-specific sections later in the guide, simply follow the subsection corresponding to your preferred tools. diff --git a/docs/developer-guide/codenameone-maven-manual/project-templates.adoc b/docs/developer-guide/Maven-Project-Templates.adoc similarity index 100% rename from docs/developer-guide/codenameone-maven-manual/project-templates.adoc rename to docs/developer-guide/Maven-Project-Templates.adoc diff --git a/docs/developer-guide/Maven-Project-Workflow.asciidoc b/docs/developer-guide/Maven-Project-Workflow.asciidoc new file mode 100644 index 0000000000..4c6381a32d --- /dev/null +++ b/docs/developer-guide/Maven-Project-Workflow.asciidoc @@ -0,0 +1,15 @@ +[[maven-project-workflow]] +== Maven Project Workflow + +Codename One uses Maven as the standard way to create, run, and maintain applications. This chapter consolidates the workflow guidance that used to live in the standalone Maven manual so the developer guide provides a single source of truth for building apps, updating projects, and managing add-ons. + +include::Maven-Introduction.adoc[leveloffset=+1] +include::Maven-Getting-Started.adoc[leveloffset=+1] +include::Maven-Updating-Codename-One.adoc[leveloffset=+1] +include::Maven-Project-Templates.adoc[leveloffset=+1] +include::Maven-Creating-CN1Libs.adoc[leveloffset=+1] +include::Maven-Appendix-Archetypes.adoc[leveloffset=+1] +include::Maven-Appendix-Goals.adoc[leveloffset=+1] +include::Maven-Appendix-API.adoc[leveloffset=+1] +include::Maven-Appendix-Control-Center.adoc[leveloffset=+1] +include::Maven-Appendix-Rich-Properties.adoc[leveloffset=+1] diff --git a/docs/developer-guide/codenameone-maven-manual/updating-cn1.adoc b/docs/developer-guide/Maven-Updating-Codename-One.adoc similarity index 86% rename from docs/developer-guide/codenameone-maven-manual/updating-cn1.adoc rename to docs/developer-guide/Maven-Updating-Codename-One.adoc index fad7fe7aa9..b87b62134c 100644 --- a/docs/developer-guide/codenameone-maven-manual/updating-cn1.adoc +++ b/docs/developer-guide/Maven-Updating-Codename-One.adoc @@ -13,9 +13,6 @@ mvn cn:update [discrete] === CLI -++++ - -++++ Alternatively you can use the `run.sh/run.bat` script to run this goal as follows: @@ -28,27 +25,21 @@ NOTE: Use `run.bat update` instead on Windows [discrete] === IntelliJ -++++ - -++++ Alternatively you can click on the "Configuration" menu, and select "Tools" > "Update Codename One" as shown here: -image::images/intellij-update-codenameone.png[] +image::img/intellij-update-codenameone.png[] -The press the image:images/intellij-run-icon.png[Run] button. +Then press the image:img/intellij-run-icon.png[Run] button. [discrete] === NetBeans -++++ - -++++ Alternatively you can right click on the project in the project inspector, and select "Run Maven" > "Update Codename One" as shown here: -image::images/netbeans-update-codenameone.png[] +image::img/netbeans-update-codenameone.png[] -Then press the image:images/netbeans-run-icon.png[Run] button. +Then press the image:img/netbeans-run-icon.png[Run] button. [discrete] === Manually Updating the pom.xml file diff --git a/docs/developer-guide/Miscellaneous-Features.asciidoc b/docs/developer-guide/Miscellaneous-Features.asciidoc index 93cf2fc6e7..6dc73b61bf 100644 --- a/docs/developer-guide/Miscellaneous-Features.asciidoc +++ b/docs/developer-guide/Miscellaneous-Features.asciidoc @@ -361,9 +361,11 @@ image::img/developer-guide/ios_strings_directory_screenshot.png[] The _strings_ format is similar to the _properties_ file format, except that both the "key" and the "value" must be wrapped in quotes. And if there are multiple strings, then they must be delimited by a semi-colon `;`. ==== -.Ant Projects +.Legacy Ant Projects **** -Ant projects have a different directory structure. They have no equivalent location to the maven _ios/src/main/strings_ directory, but its equivalent of `ios/src/main/resources` can be found at _native/ios_. To include native iOS localizations in Ant projects, you should place zipped versions of your .lproj directories inside the `native/ios` directory of your project. E.g. _en.lproj.zip_, _fr.lproj.zip_, etc. +Legacy Ant projects have a different directory structure. They have no equivalent location to the Maven _ios/src/main/strings_ directory, but the legacy `ios/src/main/resources` content can be replicated under _native/ios_. To include native iOS localizations in those projects, place zipped versions of your .lproj directories inside the `native/ios` directory. E.g. _en.lproj.zip_, _fr.lproj.zip_, etc. + +TIP: Whenever possible, migrate legacy builds to Maven to take advantage of the modern workflow. See <> for automated migration options. **** ===== Example: Localization App Usage Description Strings diff --git a/docs/developer-guide/Working-With-CodenameOne-Sources.asciidoc b/docs/developer-guide/Working-With-CodenameOne-Sources.asciidoc index 146d99e28d..27bd124b74 100644 --- a/docs/developer-guide/Working-With-CodenameOne-Sources.asciidoc +++ b/docs/developer-guide/Working-With-CodenameOne-Sources.asciidoc @@ -13,73 +13,35 @@ NOTE: Creating a clean "workspace" directory is optional, and there is nothing s === Building Sources -[source,bash] ----- -$ cd CodenameOne -$ ant ----- - -NOTE: The `cd CodenameOne` command should take you to the root project directory which contains subfolders "CodenameOne", "Ports", etc.. - not the subfolder named "CodenameOne". - -=== Running Unit Tests - -You can run the unit test suite locally in the Codename One simulator using the "test-javase" ant target. - -[source,bash] ----- -$ ant test-javase ----- - - -=== Running iOS Unit Tests - -NOTE: Running iOS Unit tests is currently limited to interal use only by Codename One. - -TLDR: You can run Codename One's unit tests on a local iOS simulator by running the "test-ios" ant target in the main CodenameOne directory. E.g. +The Maven aggregator for the SDK lives in the _maven_ directory. Run the following command to build every module and install the artifacts into your local Maven repository: [source,bash] ---- -ant test-ios +$ cd CodenameOne/maven +$ mvn -DskipTests install ---- -This assumes the following requirements - -1. You are running Mac OS X with Xcode 7.3 or higher installed. -2. You have npm installed and in your environment PATH. -3. You have appium installed and running. +TIP: Omit the `-DskipTests` flag if you want the build to execute the full test suite as part of the build. -==== Installing npm - -Either download the installer from https://nodejs.org/en/ OR run `brew install node` from terminal. - -==== Installing and Running Appium +=== Running Unit Tests -Open a new terminal window, then +Codename One's automated tests are expressed as standard Maven modules. You can run the core unit tests with: [source,bash] ---- -$ mkdir appium -$ cd appium -$ npm install appium -$ ./node_modules/.bin/appium +$ cd CodenameOne/maven +$ mvn -pl core-unittests test ---- -NOTE: You may want to run the last command `./node_modules/.bin/appium` as a daemon so that you can continue to use the same terminal window. E.g. `./node_modules/.bin/appium &` - - -==== Running the Unit tests +The integration tests that drive the simulator and build client live under the `tests` directory. From the same _maven_ directory you can run them with: [source,bash] ---- -$ cd CodenameOne -$ ant test-ios +$ mvn -pl tests -am verify ---- -==== Overriding the Codename One Build Server Target +Consult the module READMEs inside `maven/core-unittests` and `maven/tests` for additional configuration options and environment variables. -[source,bash] ----- -$ ant test-ios -Dcn1.iphone.target=iphone_new ----- +=== Running iOS Unit Tests -This will send to the "iphone_new" build server instead of the default "iphone" server. +Codename One's Appium-based iOS simulator tests require macOS, Xcode, and an Enterprise subscription. If you have access to that infrastructure, coordinate with Codename One support for credentials and provisioning, then follow the instructions in the `maven/tests` module to execute the suite with Maven. The legacy Ant targets documented in older guides are no longer part of the supported workflow. diff --git a/docs/developer-guide/codenameone-maven-manual/appendix_goal-cn1lib.adoc b/docs/developer-guide/appendix_goal-cn1lib.adoc similarity index 100% rename from docs/developer-guide/codenameone-maven-manual/appendix_goal-cn1lib.adoc rename to docs/developer-guide/appendix_goal-cn1lib.adoc diff --git a/docs/developer-guide/codenameone-maven-manual/appendix_goal_build.adoc b/docs/developer-guide/appendix_goal_build.adoc similarity index 100% rename from docs/developer-guide/codenameone-maven-manual/appendix_goal_build.adoc rename to docs/developer-guide/appendix_goal_build.adoc diff --git a/docs/developer-guide/codenameone-maven-manual/appendix_goal_clone.adoc b/docs/developer-guide/appendix_goal_clone.adoc similarity index 100% rename from docs/developer-guide/codenameone-maven-manual/appendix_goal_clone.adoc rename to docs/developer-guide/appendix_goal_clone.adoc diff --git a/docs/developer-guide/codenameone-maven-manual/appendix_goal_compliance_check.adoc b/docs/developer-guide/appendix_goal_compliance_check.adoc similarity index 100% rename from docs/developer-guide/codenameone-maven-manual/appendix_goal_compliance_check.adoc rename to docs/developer-guide/appendix_goal_compliance_check.adoc diff --git a/docs/developer-guide/codenameone-maven-manual/appendix_goal_create_gui_form.adoc b/docs/developer-guide/appendix_goal_create_gui_form.adoc similarity index 100% rename from docs/developer-guide/codenameone-maven-manual/appendix_goal_create_gui_form.adoc rename to docs/developer-guide/appendix_goal_create_gui_form.adoc diff --git a/docs/developer-guide/codenameone-maven-manual/appendix_goal_css.adoc b/docs/developer-guide/appendix_goal_css.adoc similarity index 100% rename from docs/developer-guide/codenameone-maven-manual/appendix_goal_css.adoc rename to docs/developer-guide/appendix_goal_css.adoc diff --git a/docs/developer-guide/codenameone-maven-manual/appendix_goal_designer.adoc b/docs/developer-guide/appendix_goal_designer.adoc similarity index 100% rename from docs/developer-guide/codenameone-maven-manual/appendix_goal_designer.adoc rename to docs/developer-guide/appendix_goal_designer.adoc diff --git a/docs/developer-guide/codenameone-maven-manual/appendix_goal_generate_app_project.adoc b/docs/developer-guide/appendix_goal_generate_app_project.adoc similarity index 100% rename from docs/developer-guide/codenameone-maven-manual/appendix_goal_generate_app_project.adoc rename to docs/developer-guide/appendix_goal_generate_app_project.adoc diff --git a/docs/developer-guide/codenameone-maven-manual/appendix_goal_generate_archetype.adoc b/docs/developer-guide/appendix_goal_generate_archetype.adoc similarity index 100% rename from docs/developer-guide/codenameone-maven-manual/appendix_goal_generate_archetype.adoc rename to docs/developer-guide/appendix_goal_generate_archetype.adoc diff --git a/docs/developer-guide/codenameone-maven-manual/appendix_goal_generate_cn1lib_project.adoc b/docs/developer-guide/appendix_goal_generate_cn1lib_project.adoc similarity index 100% rename from docs/developer-guide/codenameone-maven-manual/appendix_goal_generate_cn1lib_project.adoc rename to docs/developer-guide/appendix_goal_generate_cn1lib_project.adoc diff --git a/docs/developer-guide/codenameone-maven-manual/appendix_goal_generate_desktop_app_wrapper.adoc b/docs/developer-guide/appendix_goal_generate_desktop_app_wrapper.adoc similarity index 100% rename from docs/developer-guide/codenameone-maven-manual/appendix_goal_generate_desktop_app_wrapper.adoc rename to docs/developer-guide/appendix_goal_generate_desktop_app_wrapper.adoc diff --git a/docs/developer-guide/codenameone-maven-manual/appendix_goal_generate_gui_sources.adoc b/docs/developer-guide/appendix_goal_generate_gui_sources.adoc similarity index 100% rename from docs/developer-guide/codenameone-maven-manual/appendix_goal_generate_gui_sources.adoc rename to docs/developer-guide/appendix_goal_generate_gui_sources.adoc diff --git a/docs/developer-guide/codenameone-maven-manual/appendix_goal_generate_native_interfaces.adoc b/docs/developer-guide/appendix_goal_generate_native_interfaces.adoc similarity index 100% rename from docs/developer-guide/codenameone-maven-manual/appendix_goal_generate_native_interfaces.adoc rename to docs/developer-guide/appendix_goal_generate_native_interfaces.adoc diff --git a/docs/developer-guide/codenameone-maven-manual/appendix_goal_guibuilder.adoc b/docs/developer-guide/appendix_goal_guibuilder.adoc similarity index 100% rename from docs/developer-guide/codenameone-maven-manual/appendix_goal_guibuilder.adoc rename to docs/developer-guide/appendix_goal_guibuilder.adoc diff --git a/docs/developer-guide/codenameone-maven-manual/appendix_goal_install_cn1lib.adoc b/docs/developer-guide/appendix_goal_install_cn1lib.adoc similarity index 100% rename from docs/developer-guide/codenameone-maven-manual/appendix_goal_install_cn1lib.adoc rename to docs/developer-guide/appendix_goal_install_cn1lib.adoc diff --git a/docs/developer-guide/codenameone-maven-manual/appendix_goal_install_codenameone.adoc b/docs/developer-guide/appendix_goal_install_codenameone.adoc similarity index 100% rename from docs/developer-guide/codenameone-maven-manual/appendix_goal_install_codenameone.adoc rename to docs/developer-guide/appendix_goal_install_codenameone.adoc diff --git a/docs/developer-guide/codenameone-maven-manual/appendix_goal_prepare_simulator_classpath.adoc b/docs/developer-guide/appendix_goal_prepare_simulator_classpath.adoc similarity index 100% rename from docs/developer-guide/codenameone-maven-manual/appendix_goal_prepare_simulator_classpath.adoc rename to docs/developer-guide/appendix_goal_prepare_simulator_classpath.adoc diff --git a/docs/developer-guide/codenameone-maven-manual/appendix_goal_settings.adoc b/docs/developer-guide/appendix_goal_settings.adoc similarity index 100% rename from docs/developer-guide/codenameone-maven-manual/appendix_goal_settings.adoc rename to docs/developer-guide/appendix_goal_settings.adoc diff --git a/docs/developer-guide/codenameone-maven-manual/appendix_goal_test.adoc b/docs/developer-guide/appendix_goal_test.adoc similarity index 100% rename from docs/developer-guide/codenameone-maven-manual/appendix_goal_test.adoc rename to docs/developer-guide/appendix_goal_test.adoc diff --git a/docs/developer-guide/codenameone-maven-manual/appendix_goal_update.adoc b/docs/developer-guide/appendix_goal_update.adoc similarity index 100% rename from docs/developer-guide/codenameone-maven-manual/appendix_goal_update.adoc rename to docs/developer-guide/appendix_goal_update.adoc diff --git a/docs/developer-guide/codenameone-maven-manual/README.adoc b/docs/developer-guide/codenameone-maven-manual/README.adoc deleted file mode 100644 index c4a707eab9..0000000000 --- a/docs/developer-guide/codenameone-maven-manual/README.adoc +++ /dev/null @@ -1,3 +0,0 @@ -= Codename One Maven Developer Guide Repository - -This is the repository for the Codename One Maven Developer guide. See https://shannah.github.io/codenameone-maven-manual[the HTML Version]. \ No newline at end of file diff --git a/docs/developer-guide/codenameone-maven-manual/index.adoc b/docs/developer-guide/codenameone-maven-manual/index.adoc deleted file mode 100644 index bbdd203de5..0000000000 --- a/docs/developer-guide/codenameone-maven-manual/index.adoc +++ /dev/null @@ -1,27 +0,0 @@ -= Codename One Maven Developer Guide -Steve Hannah -:doctype: book -:encoding: utf-8 -:lang: en -:toc: left -:docinfo: private - -include::introduction.adoc[] - -include::getting-started.adoc[] - -include::updating-cn1.adoc[] - -include::project-templates.adoc[] - -include::creating-cn1libs.adoc[] - -include::appendix_archetypes.adoc[] - -include::appendix_goals.adoc[] - -include::appendix_api.adoc[] - -include::appendix_control_center.adoc[] - -include::appendix_rich_properties_file.adoc[] diff --git a/docs/developer-guide/codenameone-maven-manual/introduction.adoc b/docs/developer-guide/codenameone-maven-manual/introduction.adoc deleted file mode 100644 index e7ce6ac4fc..0000000000 --- a/docs/developer-guide/codenameone-maven-manual/introduction.adoc +++ /dev/null @@ -1,43 +0,0 @@ -== Introduction - -Starting in version 8.0, Codename One will be migrating to Maven as its primary build tool. This guide aims to be the definitive source of information for this new project structure. - -=== Conventions - -This document includes instructions for command-line, NetBeans, and IntelliJ IDEA. Eclipse documentation is forthcoming. To improve the flow of the document, it provides toggle buttons to choose which instructions you prefer to follow, as shown below: - -==== CLI -++++ - -++++ - -These are Command-line instructions. Click on the small gray buttons above and to the right to see these instructions for IntelliJ or NetBeans. - -Your selection will be remembered throughout the rest of the document. - -==== IntelliJ -++++ - -++++ - -These are IntelliJ IDEA instructions. Click on the small gray buttons above and to the right to see these instructions for Command-line, Eclipse, or NetBeans. - -Your selection will be remembered throughout the rest of the document. - -==== NetBeans -++++ - -++++ - -These are NetBeans instructions. Click on the small gray buttons above and to the right to see these instructions for IntelliJ, Eclipse, or Command-line. - -Your selection will be remembered throughout the rest of the document. - -==== Eclipse -++++ - -++++ - -These are Eclipse instructions. Click on the small gray buttons above and to the right to see these instructions for IntelliJ, NetBeans or Command-line. - -Your selection will be remembered throughout the rest of the document. \ No newline at end of file diff --git a/docs/developer-guide/developer-guide.asciidoc b/docs/developer-guide/developer-guide.asciidoc index 39819842eb..66232ad8ef 100644 --- a/docs/developer-guide/developer-guide.asciidoc +++ b/docs/developer-guide/developer-guide.asciidoc @@ -36,7 +36,11 @@ toc::[] include::About-This-Guide.asciidoc[] -= Part I. Foundations += Part I. Project Setup + +include::Maven-Project-Workflow.asciidoc[] + += Part II. Foundations include::Index.asciidoc[] @@ -48,7 +52,7 @@ include::Advanced-Theming.asciidoc[] include::css.asciidoc[] -= Part II. User Interface and Experience += Part III. User Interface and Experience include::The-Components-Of-Codename-One.asciidoc[] @@ -58,7 +62,7 @@ include::The-EDT---Event-Dispatch-Thread.asciidoc[] include::graphics.asciidoc[] -= Part III. Application Services += Part IV. Application Services include::Events.asciidoc[] @@ -72,7 +76,7 @@ include::performance.asciidoc[] include::Monetization.asciidoc[] -= Part IV. Platform and Deployment += Part V. Platform and Deployment include::Advanced-Topics-Under-The-Hood.asciidoc[] @@ -86,7 +90,7 @@ include::Working-With-Javascript.asciidoc[] include::Working-with-Mac-OS-X.asciidoc[] -= Part V. Contributing and Appendices += Part VI. Contributing and Appendices include::Working-With-CodenameOne-Sources.asciidoc[]