diff --git a/docs/demos/common/src/main/snippets/developer-guide/working-with-windows.sh b/docs/demos/common/src/main/snippets/developer-guide/working-with-windows.sh index f1beb009283..1230d8383f6 100644 --- a/docs/demos/common/src/main/snippets/developer-guide/working-with-windows.sh +++ b/docs/demos/common/src/main/snippets/developer-guide/working-with-windows.sh @@ -1,5 +1,5 @@ // Generated from docs/developer-guide source blocks. Edit the guide snippets here, not inline. // tag::working-with-windows-bash-001[] -mvn -pl common package -Dcodename1.platform=windows -Dcodename1.buildTarget=windows-device +mvn package -Dcodename1.platform=win -Dcodename1.buildTarget=windows-device // end::working-with-windows-bash-001[] diff --git a/docs/developer-guide/Introduction.asciidoc b/docs/developer-guide/Introduction.asciidoc index 3ba32d08f6d..2f9172686f7 100644 --- a/docs/developer-guide/Introduction.asciidoc +++ b/docs/developer-guide/Introduction.asciidoc @@ -60,13 +60,13 @@ Codename One uses a SaaS-based approach so the information in this appendix migh Since Android is already based on Java, Codename One is already native to Android and works with the Android VM (ART/Dalvik). -On iOS, Codename One built and open-sourced ParparVM, which is a conservative VM. ParparVM features a concurrent, non-blocking GC and is written entirely in Java/C. ParparVM is a transpiler that generates C source code matching the given Java bytecode. This means that an Xcode project is generated and compiled on the build servers. It's as if you hand-coded a native app and is thus future-proof against changes that Apple introduces. For example, Apple migrated to 64-bit and later introduced bitcode support to iOS. ParparVM needed no modifications to meet those changes. +On iOS, Codename One built and open-sourced ParparVM, which is a conservative VM. ParparVM features a concurrent, non-blocking GC and is written entirely in Java/C. ParparVM is a transpiler that generates C source code matching the given Java bytecode. This means that an Xcode project is generated and compiled on the build servers. It's as if you hand-coded a native app and is thus future-proof against changes that Apple introduces. For example, Apple migrated to 64-bit, then introduced bitcode, then withdrew bitcode again. ParparVM needed no modifications for any of those changes. NOTE: Codename One translates the bytecode to C, which is faster than Swift/Objective-C. The port code that invokes iOS APIs is hand coded in Objective-C Codename One earlier offered a UWP (Universal Windows Platform) target based on iKVM. That target was discontinued in release 7.0.229 and is preserved as historical context in older documentation and blog posts. -JavaScript build targets use TeaVM to do the translation statically. TeaVM supports threading using JavaScript by breaking the app down in a rather elaborate way. To support the complex UI Codename One uses the HTML5 Canvas API which allows absolute flexibility for building applications. +JavaScript build targets translate the bytecode statically with ParparVM, the same translator that generates the C sources for iOS. Cloud builds keep the original TeaVM-based compiler as a compatibility fallback, which you select with the `javascript.port` build hint. To support the complex UI Codename One uses the HTML5 Canvas API which allows absolute flexibility for building applications. For desktop builds Codename One uses `javapackager`, since both Macs and Windows machines are available in the cloud, the platform-specific nature of `javapackager` isn't a problem. @@ -87,7 +87,7 @@ Lightweight components date back to Smalltalk frameworks, this notion was popula ===== Why ParparVM -On iOS, Codename One uses https://github.com/codenameone/CodenameOne/tree/master/vm[ParparVM] which translates Java bytecode to C code and boasts a non-blocking GC as well as 64 bit/bitcode support. This VM is fully open source in the https://github.com/codenameone/CodenameOne/[Codename One git repository]. In the past Codename One used http://www.xmlvm.org/[XMLVM] to generate native code similarly, but the XMLVM solution was too generic for the needs of Codename One. https://github.com/codenameone/CodenameOne/tree/master/vm[ParparVM] boasts a unique architecture of translating code to C (similarly to XMLVM), because of that Codename One is the only solution of its kind that can **guarantee** future iOS compatibility since the officially supported iOS toolchain is always used instead of undocumented behaviors. +On iOS, Codename One uses https://github.com/codenameone/CodenameOne/tree/master/vm[ParparVM] which translates Java bytecode to C code and boasts a non-blocking GC. This VM is fully open source in the https://github.com/codenameone/CodenameOne/[Codename One git repository]. In the past Codename One used http://www.xmlvm.org/[XMLVM] to generate native code similarly, but the XMLVM solution was too generic for the needs of Codename One. https://github.com/codenameone/CodenameOne/tree/master/vm[ParparVM] boasts a unique architecture of translating code to C (similarly to XMLVM), because of that Codename One is the only solution of its kind that can **guarantee** future iOS compatibility since the officially supported iOS toolchain is always used instead of undocumented behaviors. NOTE: XMLVM could guarantee that as well, but it's no longer maintained and lacked the API layer support @@ -107,7 +107,7 @@ NOTE: The UWP target was discontinued in release 7.0.229 and is no longer part o ===== JavaScript port -The JavaScript port of Codename One uses ParparVM to translate Java bytecode into JavaScript. Cloud builds retain the original http://teavm.org:[TeaVM-based builder] as a compatibility fallback, selected with the public `javascript.port=teavm` build hint. +The JavaScript port of Codename One uses ParparVM to translate Java bytecode into JavaScript. Cloud builds retain the original https://teavm.org/[TeaVM-based builder] as a compatibility fallback, selected with the public `javascript.port=teavm` build hint. The JavaScript port allows unmodified Codename One applications to run within a desktop or mobile browser. The port itself is based on the HTML5 Canvas API, which provides a pixel-perfect implementation of the Codename One API. @@ -175,9 +175,9 @@ Scrolling poses another challenge in touch-based interfaces. In desktop applicat Some developers single out this wide range of resolutions and densities as "`device fragmentation.`" While it does contribute to development complexity, it isn't a challenging problem to overcome. -Densities aren't the cause of device fragmentation. Device fragmentation is caused by many OS versions with different behaviors. This is clear on Android and relates to the slow rollout of Android vendor versions compared to Google rollout. For example, 7 months after the Android 8 (Oreo) release in 2018, it was still available on 1.1% of the devices. The damning statistic is that 12% of the devices in mid 2018 run Android 4.4 Kitkat released in 2013! (((Google))) +Densities aren't the cause of device fragmentation. Device fragmentation is caused by many OS versions with different behaviors. This is clear on Android and relates to the slow rollout of Android vendor versions compared to Google rollout. A new release reaches only a small fraction of devices in its first year, and handsets several major versions behind stay in circulation long after their vendor stops shipping updates for them. (((Google))) -This makes QA difficult as the disparity between these versions is pretty big. These numbers will be out of date by the time you read this, but the core problem remains. It's hard to get all device manufacturers aligned, so this problem will probably remain in the foreseeable future despite everything. +This makes QA difficult as the disparity between these versions is pretty big. It's hard to get all device manufacturers aligned, so this problem will probably remain in the foreseeable future despite everything. ==== Performance @@ -414,7 +414,7 @@ First, the good news: In iOS Apple issues the certificates for your applications. That way the certificate is trusted by Apple and is assigned to your Apple iOS developer account. One important caveat applies: You need an iOS Developer Account and Apple charges a 99USD Annual fee for that. -TIP: The 99USD price and need have been around since the introduction of the iOS developer program for 10 years at the time of this writing. It might change at some point though +TIP: The fee and the requirement have been part of the iOS developer program since it was introduced. Check Apple's developer site for the current price. Apple also requires a "`provisioning profile`" which is a special file bound to your certificate and app. This file describes some details about the app to the iOS installation process. One of the details it includes during development is the list of permitted devices. @@ -453,12 +453,7 @@ One important aspect of provisioning on iOS is the device list in the provisioni WARNING: Many apps and tools offer the UDID of the device, but they aren't necessarily reliable and might give a fake number! -.Get the UDID of a Device -image::img/get-device-udid.png[Get the UDID of a Device] - -TIP: You can right-click the UDID and select #copy# to copy it - -The simplest and most reliable process for getting a UDID is through iTunes. Other approaches have worked in the past but this approach is guaranteed. +The <<_whats_udid,UDID section of the signing chapter>> covers the reliable ways to read that value. NOTE: Ad hoc provisioning allows 1000 beta testers for your application but it's a more complex process that you won't discuss here although it's supported by Codename One @@ -466,10 +461,9 @@ NOTE: Ad hoc provisioning allows 1000 beta testers for your application but it's Before you continue with the build you should sign up at https://www.codenameone.com/build-server.html where you can soon follow the progress of your builds. You need a Codename One account to build for the device. -Now that you have certificates, the process of device builds is a right click away for both OSes. You can right-click the project and select #Codename One# -> #Send iOS Debug Build# or #Codename One# -> #Send Android Build#. +Now that you have certificates, a device build is a single Maven goal. From the project's root directory run `mvn cn1:buildAndroid` for Android, or `mvn cn1:buildIos` for an iOS debug build. Each one packages the app, sends it to the Codename One build servers and reports where the result lands. -.Right click menu options for sending device builds -image::img/getting-started-right-click-menu.png[Right click menu options for sending device builds,scaledwidth=50%] +WARNING: Run these from the root, not from a module. The build goals skip any project that isn't the execution root, so `mvn -pl common cn1:buildAndroid` prints "`Skipping execution for non-root project`" and then reports success without building anything. NOTE: The first time you send a build you will be prompted for the email and password you provided when signing up for Codename One diff --git a/docs/developer-guide/Working-With-Windows.asciidoc b/docs/developer-guide/Working-With-Windows.asciidoc index 33aa88bc93e..d9f97a2b141 100644 --- a/docs/developer-guide/Working-With-Windows.asciidoc +++ b/docs/developer-guide/Working-With-Windows.asciidoc @@ -84,7 +84,7 @@ above. Trigger it like any other cloud target: include::../demos/common/src/main/snippets/developer-guide/working-with-windows.sh[tag=working-with-windows-bash-001,indent=0] ---- -The convenience goal `mvn -pl common cn1:buildWin32` does the same thing. A regular +The convenience goal `mvn cn1:buildWin32`, run from the project root, does the same thing. A regular (release) build returns **two** binaries -- x64 and arm64, both stripped release exes. Setting the `windows.debug` build hint instead returns a **single** x64 exe with symbols, for diagnosis. (To build locally on a Windows box, use diff --git a/docs/developer-guide/img/get-device-udid.png b/docs/developer-guide/img/get-device-udid.png deleted file mode 100644 index 1ce13e38367..00000000000 Binary files a/docs/developer-guide/img/get-device-udid.png and /dev/null differ diff --git a/docs/developer-guide/img/getting-started-right-click-menu.png b/docs/developer-guide/img/getting-started-right-click-menu.png deleted file mode 100644 index 23021c621ce..00000000000 Binary files a/docs/developer-guide/img/getting-started-right-click-menu.png and /dev/null differ diff --git a/maven/codenameone-maven-plugin/src/main/java/com/codename1/maven/buildWrappers/BuildWin32Mojo.java b/maven/codenameone-maven-plugin/src/main/java/com/codename1/maven/buildWrappers/BuildWin32Mojo.java index 0e30ea08ac6..f0c0efaf554 100644 --- a/maven/codenameone-maven-plugin/src/main/java/com/codename1/maven/buildWrappers/BuildWin32Mojo.java +++ b/maven/codenameone-maven-plugin/src/main/java/com/codename1/maven/buildWrappers/BuildWin32Mojo.java @@ -23,7 +23,14 @@ public class BuildWin32Mojo extends AbstractBuildWrapperMojo { @Override protected String getPlatform() { - return "windows"; + // "win", not "windows". This value activates the module profile in the + // generated project's root pom, and that profile matches the value the + // win module itself declares -- which is "win". Passing "windows" + // matched no profile, so the win module never entered the reactor and + // the wrapper's nested build reported success having produced nothing. + // Nothing else reads the platform as "windows"; the build TARGET stays + // "windows-device", which is a separate namespace. + return "win"; } @Override diff --git a/maven/codenameone-maven-plugin/src/main/java/com/codename1/maven/buildWrappers/BuildWindowsDeviceMojo.java b/maven/codenameone-maven-plugin/src/main/java/com/codename1/maven/buildWrappers/BuildWindowsDeviceMojo.java index 4b098dd4861..24189ffc4dc 100644 --- a/maven/codenameone-maven-plugin/src/main/java/com/codename1/maven/buildWrappers/BuildWindowsDeviceMojo.java +++ b/maven/codenameone-maven-plugin/src/main/java/com/codename1/maven/buildWrappers/BuildWindowsDeviceMojo.java @@ -15,7 +15,14 @@ public class BuildWindowsDeviceMojo extends AbstractBuildWrapperMojo { @Override protected String getPlatform() { - return "windows"; + // "win", not "windows". This value activates the module profile in the + // generated project's root pom, and that profile matches the value the + // win module itself declares -- which is "win". Passing "windows" + // matched no profile, so the win module never entered the reactor and + // the wrapper's nested build reported success having produced nothing. + // Nothing else reads the platform as "windows"; the build TARGET stays + // "windows-device", which is a separate namespace. + return "win"; } @Override diff --git a/scripts/developer-guide/guide-links-baseline.txt b/scripts/developer-guide/guide-links-baseline.txt index 990e6d1c4d0..56648f6ac60 100644 --- a/scripts/developer-guide/guide-links-baseline.txt +++ b/scripts/developer-guide/guide-links-baseline.txt @@ -21,7 +21,6 @@ Advanced-Topics-Under-The-Hood.asciidoc http://jruby.org/ Advanced-Topics-Under-The-Hood.asciidoc http://shannah.github.io/cn1-freshdesk/ Advanced-Topics-Under-The-Hood.asciidoc http://stackoverflow.com/questions/11421048/android-ios-custom-uri-protocol-handling Advanced-Topics-Under-The-Hood.asciidoc http://www.mirah.org/ -Introduction.asciidoc http://teavm.org Introduction.asciidoc http://www.xmlvm.org/ Miscellaneous-Features.asciidoc http://wiki.akosma.com/IPhone_URL_Schemes The-Components-Of-Codename-One.asciidoc http://awoiaf.westeros.org/index.php/A_Game_of_Thrones