diff --git a/SDK6UserGuide/appendix/dependenciesConfigurations.rst b/SDK6UserGuide/appendix/dependenciesConfigurations.rst index 1eb6e6d05..c1b6fecb5 100644 --- a/SDK6UserGuide/appendix/dependenciesConfigurations.rst +++ b/SDK6UserGuide/appendix/dependenciesConfigurations.rst @@ -31,7 +31,6 @@ The MicroEJ Gradle plugins also define dependency configurations for internal us - ``microejRuntimeEnvironmentFullRuntimeClasspath``, used by the :ref:`sdk6_module_natures.tasks.buildVirtualDevice`, :ref:`sdk6_module_natures.tasks.buildApplicationObjectFile` and :ref:`sdk6_module_natures.tasks.buildExecutable` tasks - ``microejFullRuntimeClasspath``, used by the :ref:`sdk6_module_natures.tasks.runOnSimulator` and :ref:`sdk6_module_natures.tasks.buildApplicationObjectFile` tasks - ``microejVeeFullClasspath``, used by the :ref:`sdk6_module_natures.tasks.loadVee` task - - ``microejVeeCompileClasspath``, used by the :ref:`sdk6_module_natures.application` plugin - ``microejVeeRuntimeClasspath``, used by the :ref:`sdk6_module_natures.application` plugin .. _gradle_veeport_project_dependencies_configurations: diff --git a/SDK6UserGuide/appendix/index.rst b/SDK6UserGuide/appendix/index.rst index cc928ebf7..f501d7253 100644 --- a/SDK6UserGuide/appendix/index.rst +++ b/SDK6UserGuide/appendix/index.rst @@ -9,7 +9,7 @@ Appendices applicationWrapper cheatsheet javaLambdas - veePortTransitivity + veeTransitivity .. | Copyright 2008-2025, MicroEJ Corp. Content in this space is free diff --git a/SDK6UserGuide/appendix/veePortTransitivity.rst b/SDK6UserGuide/appendix/veePortTransitivity.rst deleted file mode 100644 index 2d24aa0c3..000000000 --- a/SDK6UserGuide/appendix/veePortTransitivity.rst +++ /dev/null @@ -1,47 +0,0 @@ -.. _gradle_vee_transitivity_chapter: - -VEE Port transitivity -===================== - -Starting from SDK 6 ``1.4.0``, it is possible to enable the :ref:`transitive resolution of the VEE Port `. -This allows to include the transitive dependencies of the VEE Port in the compile classpath and runtime classpath of the project, -depending on the configuration used to define the Libraries in your VEE Port (``microejPack``, ``api``, ``implementation``): - -- The Libraries defined with ``microejPack`` and ``api`` and their transitive dependencies are added to the compile classpath and runtime classpath of the project. -- The Libraries defined with ``implementation`` and their transitive dependencies are added to the runtime classpath of the project. - -For example, if your VEE Port provides the following Libraries:: - - dependencies { - microejPack("org.example:lib1:1.0.0") - api("org.example:lib2:1.0.0") - implementation("org.example:lib3:1.0.0") - } - -the ``lib3`` library will be added to the runtime classpath of your project, and the ``lib1`` and ``lib2`` will be added to both compile classpath and runtime classpath. - -.. note:: - - In a VEE Port project, the ``microejPack`` configuration can be used to define an SDK 5 Pack or an SDK 6 Library. - The ``api`` and ``implementation`` configurations are used to define SDK 6 Libraries only. - -If the provided VEE Port is used only for :ref:`testsuites `, the Libraries provided by the VEE Port are used -to build the runtime classpath of the testsuites, not to compile the project. - -.. warning:: - - It is important to note that a VEE Port allowing to resolve transitively its Libraries is required, so if your project uses: - - - a VEE Port built with SDK 6 ``1.2.0`` or older - - a VEE Port built with SDK 5 - - a local VEE Port Directory - - a local VEE Port archive file - - it is highly recommended to update your VEE Port project to SDK 6 ``1.3.0`` or higher as the feature will be enabled by default in the next SDK 6 major version. - -.. - | Copyright 2008-2025, MicroEJ Corp. Content in this space is free - for read and redistribute. Except if otherwise stated, modification - is subject to MicroEJ Corp prior approval. - | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and - copyrights are the property of their respective owners. diff --git a/SDK6UserGuide/appendix/veeTransitivity.rst b/SDK6UserGuide/appendix/veeTransitivity.rst new file mode 100644 index 000000000..01d27f499 --- /dev/null +++ b/SDK6UserGuide/appendix/veeTransitivity.rst @@ -0,0 +1,90 @@ +.. _gradle_vee_transitivity_chapter: + +VEE transitivity +================ + +Starting from SDK 6 ``1.4.0``, it is possible to enable the transitive resolution of a :ref:`VEE Port ` or +a :ref:`Kernel `. This allows to use the transitive dependencies of the provided VEE to compile and build the project. + +VEE Port transitivity +~~~~~~~~~~~~~~~~~~~~~ + +When a VEE Port is resolved transitively, its transitive dependencies are added to the compile classpath and runtime classpath of the project depending on +the configuration used to define the Libraries in the VEE Port (``microejPack``, ``api``, ``implementation``): + +- The Libraries defined with ``microejPack`` and ``api`` and their transitive dependencies are added to the compile classpath and runtime classpath of the project. +- The Libraries defined with ``implementation`` and their transitive dependencies are added to the runtime classpath of the project. + +For example, if your VEE Port provides the following Libraries:: + + dependencies { + implementation("org.example:lib1:1.0.0") + microejPack("org.example:lib2:1.0.0") + api("org.example:lib3:1.0.0") + } + +the ``lib1`` library will be added to the runtime classpath of your project, and the ``lib2`` and ``lib3`` libraries will be added to both compile classpath and runtime classpath. + +.. note:: + + In a VEE Port project, the ``microejPack`` configuration can be used to define an SDK 5 Pack or an SDK 6 Library. + The ``api`` and ``implementation`` configurations are used to define SDK 6 Libraries only. + +If the provided VEE Port is used only for :ref:`testsuites `, the Libraries provided by the VEE Port are used +to build the runtime classpath of the testsuites, not to compile the project. + +.. warning:: + + It is important to note that a VEE Port allowing to resolve transitively its Libraries is required, so if your project uses: + + - a VEE Port built with SDK 6 ``1.2.0`` or older + - a VEE Port built with SDK 5 + + it is highly recommended to update your VEE Port to SDK 6 ``1.3.0`` minimum as the feature will be enabled by default in the next SDK 6 major version. + This limitation does not concern VEE Ports available locally :ref:`in a directory ` or + :ref:`as an archive `. + +Kernel transitivity +~~~~~~~~~~~~~~~~~~~ + +When a Kernel is resolved transitively, its Jar file and its transitive dependencies are added to the compile classpath and runtime classpath of the project depending on +the configuration used to define the Libraries in the Kernel: + +- The Libraries defined with ``api`` and their transitive dependencies are added to the compile classpath and runtime classpath of the project. +- The Libraries defined with ``implementation`` and their transitive dependencies are added to the runtime classpath of the project. + +For example, if your project depends on a Kernel which defined the following dependencies:: + + dependencies { + implementation("org.example:lib1:1.0.0") + api("org.example:lib2:1.0.0") + } + +the ``lib1`` library will be added to the runtime classpath of your project, and the ``lib2`` library will be added to both compile classpath and runtime classpath. + +This behavior is common to any project applying `Java Library plugin `__. +However, it is important to note that the APIs of a Library defined with ``api`` in your Kernel will be exposed to Applications. + +To ensure that a dependency defined in a Kernel is not exposed to Applications by mistake, it is highly recommended to use ``implementation`` instead of ``api`` +(or ``compileOnly`` instead of ``compileOnlyApi``) when declaring dependencies in your Kernel project. + + +If the provided Kernel is used only for :ref:`testsuites `, the Libraries provided by the Kernel are used +to build the runtime classpath of the testsuites, but they are not used to compile the project. + +.. warning:: + + It is important to note that a Kernel allowing to publish its Runtime Environment and to resolve transitively its Libraries is required, so if your project uses: + + - a Kernel built with SDK 6 ``1.2.0`` or older + - a Kernel built with SDK 5 + + it is highly recommended to update your Kernel to SDK 6 ``1.3.0`` minimum as the feature will be enabled by default in the next SDK 6 major version. + This limitation does not concern Kernels :ref:`available locally `. + +.. + | Copyright 2008-2025, MicroEJ Corp. Content in this space is free + for read and redistribute. Except if otherwise stated, modification + is subject to MicroEJ Corp prior approval. + | MicroEJ is a trademark of MicroEJ Corp. All other trademarks and + copyrights are the property of their respective owners. diff --git a/SDK6UserGuide/limitations.rst b/SDK6UserGuide/limitations.rst index a6db691a9..e1cbb0acd 100644 --- a/SDK6UserGuide/limitations.rst +++ b/SDK6UserGuide/limitations.rst @@ -18,15 +18,9 @@ It is also important to note the following SDK 5 / SDK 6 compatibility rules: - SDK 6 Virtual Device cannot be used by SDK 5 Applications. - SDK 5 Virtual Device cannot be used to build the Virtual Device of a SDK 6 Application (augmented Virtual Device). -When the :ref:`VEE Port transitive resolution ` is enabled, the following VEE Ports are not supported: - -- VEE Ports built with SDK 6 ``1.2.0`` or older -- SDK 5 VEE Ports -- local VEE Port Directory -- local VEE Port archive file - -The feature will be enabled by default in the next SDK 6 major version, so it is highly recommended to update your VEE Port if it does not allow to be -transitively resolved. +When :ref:`the VEE Port transitive resolution ` is enabled, +the VEE Ports and Kernels built with SDK 6 prior to ``1.3.0`` or SDK 5 are not supported, except if they are available locally in a directory or as an archive. +It is highly recommended to update your VEE Port or Kernel if necessary, as the feature will be enabled by default in the next SDK 6 major version. .. | Copyright 2008-2025, MicroEJ Corp. Content in this space is free diff --git a/SDK6UserGuide/moduleNatures.rst b/SDK6UserGuide/moduleNatures.rst index fe7f44868..b37cc5202 100644 --- a/SDK6UserGuide/moduleNatures.rst +++ b/SDK6UserGuide/moduleNatures.rst @@ -68,6 +68,7 @@ This plugin adds the following tasks to your project: - :ref:`sdk6_module_natures.tasks.generateApplicationWrapper` - :ref:`sdk6_module_natures.tasks.compileWrapperJava` - :ref:`sdk6_module_natures.tasks.buildFeatureFromWPK` +- :ref:`sdk6_module_natures.tasks.shrinkRuntimeEnvironment` .. graphviz:: graphApplicationModule.dot @@ -622,6 +623,7 @@ shrinkRuntimeEnvironment This task is used by the following module natures: - :ref:`sdk6_module_natures.runtime-environment` +- :ref:`sdk6_module_natures.application` The ``shrinkRuntimeEnvironment`` task is used internally by the SDK and it is not intended to be executed by the user. diff --git a/SDK6UserGuide/selectKernel.rst b/SDK6UserGuide/selectKernel.rst index b5bd5fa9e..0c1287cec 100644 --- a/SDK6UserGuide/selectKernel.rst +++ b/SDK6UserGuide/selectKernel.rst @@ -7,6 +7,8 @@ Building the Feature file of an Application with the SDK requires a Kernel. Use one of the following available options to provide it to your project. +.. _sdk_6_select_kernel_module: + Using a Module Dependency ~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -17,16 +19,68 @@ you can define the Kernel by declaring a module dependency in the ``build.gradle microejVee("com.mycompany:mykernel:1.0.0") } -Using a Project Dependency -~~~~~~~~~~~~~~~~~~~~~~~~~~ +.. _sdk_6_select_kernel_in_multiproject: + +Kernel project inside a multi-project +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When the Kernel project is in the same multi-project than the component which needs it (an Application for example), +the Kernel project should be declared as a project dependency. + +For example if the multi-project contains an Application subproject named ``my-app`` and a Kernel subproject called ``my-kernel``, +the Kernel project must be declared as a dependency in the ``build.gradle.kts`` file of the ``my-app`` subproject as follows:: + + dependencies { + + microejVee(project(":my-kernel")) + + } + +To find the name of the Kernel project, you can execute the ``projects`` task on the multi-project to display all its subprojects, for example:: + + Root project 'my-multi-project' + +--- Project ':application' + +--- Project ':library' + \--- Project ':my-kernel' + +The Kernel Virtual Device and Executable will be automatically built when they are required by the Application. +For example the Virtual Device will be built before running the Application on the Simulator (with the ``runOnSimulator`` task), +and the Executable will be built before building the Application Feature (with the ``buildFeature`` task). + +.. _sdk_6_select_kernel_outside_multi-project: + +Local Kernel project outside a multi-project +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +When the Application or the Library which needs the Kernel is not in the same multi-project than the Kernel, +the Kernel project can be imported thanks to the `Gradle Composite Build `_ feature. + +This allows to consider the Kernel project as part of the Application project, +so all changes done to the Kernel are automatically considered when building or running the Application. + +This is done by adding the following line in the ``settings.gradle.kts`` file of the Application project:: + + includeBuild("[kernel-project-path]") + +Then declaring the Kernel as a dependency in the ``build.gradle.kts`` file of the Application project:: + + dependencies { + + microejVee("com.mycompany:my-kernel:1.0.0") + + } + +The dependency must use the module notation (``"group:name:version"``), where the group and name match with the ones declared in the Kernel project. +The group is defined in the ``build.gradle.kts`` file of the ``my-kernel`` project by the ``group`` property. +To find the name of the Kernel project, you can execute the ``projects`` task on the multi-project to display all its subprojects, for example:: + + Root project 'my-multi-project' + +--- Project ':application' + +--- Project ':library' + \--- Project ':my-kernel' + +.. _sdk_6_select_local_kernel: -When your Kernel is a subproject of a multi-project, -you can define the Kernel by declaring a project dependency in the ``build.gradle.kts`` file, with the ``microejVee`` configuration:: - - dependencies { - microejVee(project(":mykernel")) - } - Using a Local Kernel ~~~~~~~~~~~~~~~~~~~~ @@ -37,12 +91,49 @@ you can use its Virtual Device and its Executable by declaring a file dependency microejVee(files("C:\\path\\to\\my\\kernel\\virtual\\device", "C:\\path\\to\\my\\kernel\\executable.out")) } +This is generally the case when the VEE Port has been built locally + +- in SDK 6, by executing the ``buildVirtualDevice`` and ``buildExecutable`` Gradle tasks on the Kernel project. + In this case, the Virtual directory is located in the ``build/virtualDevice`` of the project and the Executable is located in the ``build/application/executable`` folder. + +.. warning:: + + It is recommended to :ref:`include the Kernel project ` instead of using a file dependency to ensure that any change done to + the Kernel project is considered when building your Application without having to manually rebuild the Virtual Device and the Executable. + +- in SDK 5, by executing a ``Build Module`` on the Kernel project. + In this case, the Virtual Device archive file and the Executable are located in the ``target~/artifacts`` folder of the Kernel project. + .. note:: - This file, as well as other Gradle configuration files, respects the Java properties file convention: + The ``build.gradle.kts`` file, as well as other Gradle configuration files, respects the Java properties file convention: the OS path must use the UNIX path convention (path separator is ``/``). The Windows paths must have been converted manually replacing ``\`` by ``/`` or by ``\\``. +.. _sdk_6_kernel_transitivity: + +Resolve a Kernel transitively +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. warning:: + + The transitive resolution of a Kernel is not supported for Kernels built with SDK 5 or SDK 6 ``1.2.0`` or older provided + as :ref:`module ` or :ref:`project `. + While this feature is optional for now, it will be enabled by default in the next SDK 6 major version, so it is highly recommended to update your Kernel if necessary. + +By default, the Kernel is not fetched transitively by consumer projects, but starting from SDK 6 ``1.4.0``, it is possible to enable the transitivity of the Kernel by: + +- Setting the project property ``feature.vee.transitivity.enabled`` to ``true`` in command line with the ``-P`` argument:: + + ./gradlew runOnSimulator -Pfeature.vee.transitivity.enabled=true + +- or by adding it in the ``gradle.properties`` file of your project:: + + feature.vee.transitivity.enabled=true + +When the feature is enabled, the Jar file of the Kernel and its transitive dependencies are fetched to build the compile classpath and runtime classpath of the project. +For more information about the transitivity of the Kernel, refer to :ref:`gradle_vee_transitivity_chapter`. + .. | Copyright 2008-2025, MicroEJ Corp. Content in this space is free for read and redistribute. Except if otherwise stated, modification diff --git a/SDK6UserGuide/selectVeePort.rst b/SDK6UserGuide/selectVeePort.rst index bcc00c9ec..d8f23d7ca 100644 --- a/SDK6UserGuide/selectVeePort.rst +++ b/SDK6UserGuide/selectVeePort.rst @@ -72,7 +72,7 @@ and the :ref:`Architecture Usage ` of the VE The VEE Port will be automatically built when it is required by the Application. For example when running the Application on the Simulator (with the ``runOnSimulator`` task) -or when building the Application Executable (with the ``buildExecutable``), +or when building the Application Executable (with the ``buildExecutable`` task), the VEE Port will be built before executing the requested task. .. _sdk_6_select_veeport_outside_multi-project: @@ -80,7 +80,7 @@ the VEE Port will be built before executing the requested task. Local VEE Port project outside a multi-project ---------------------------------------------- -When the Application or the Library which needs the VEE Port is not is the same multi-project than the VEE Port, +When the Application or the Library which needs the VEE Port is not in the same multi-project than the VEE Port, the VEE Port project can be imported thanks to the `Gradle Composite Build `_ feature. This allows to consider the VEE Port project as part of the Application project, @@ -88,7 +88,7 @@ so all changes done to the VEE Port are automatically considered when building o This is done by adding the following line in the ``settings.gradle.kts`` file of the Application project:: - includeBuild("[vee-port-project-absolute-path]") + includeBuild("[vee-port-project-path]") Then declaring the VEE Port as a dependency in the ``build.gradle.kts`` file of the Application project:: @@ -108,16 +108,11 @@ For example, the name of the VEE Port is ``my-custom-vee-port`` if the ``vee-por Otherwise the name of the subproject folder is used, so ``vee-port`` in the recommended structure. - .. _sdk_6_select_veeport_local_directory: Using a Local VEE Port Directory -------------------------------- -.. warning:: - - A local VEE Port Directory can not be used if the transitive resolution of the VEE Port is enabled, refer to :ref:`sdk_6_vee_port_transitivity` for more information. - When your VEE Port is available in a local directory, you can use it by declaring a file dependency in the ``build.gradle.kts`` file, with the ``microejVee`` configuration:: @@ -129,12 +124,18 @@ This is generally the case when the VEE Port has been built locally - in SDK 6, by executing the ``buildVeePort`` Gradle task on the VEE Port project. In this case, the VEE Port directory is located at ``build/veePort/source`` in the project. + +.. warning:: + + It is recommended to :ref:`include the VEE Port project ` instead of using a file dependency to ensure that any change done + to the VEE Port project is considered when building your Application without having to manually rebuild the VEE Port. + - in SDK 5, by executing a ``Build Module`` on the VEE Port configuration project. In this case, the VEE Port is a sibling folder of the VEE Port configuration project, named after the VEE Port name. .. note:: - This file, as well as other Gradle configuration files, respects the Java properties file convention: + The ``build.gradle.kts`` file, as well as other Gradle configuration files, respects the Java properties file convention: the OS path must use the UNIX path convention (path separator is ``/``). The Windows paths must have been converted manually replacing ``\`` by ``/`` or by ``\\``. @@ -143,10 +144,6 @@ This is generally the case when the VEE Port has been built locally Using a Local VEE Port Archive ------------------------------ -.. warning:: - - A local VEE Port Archive can not be used if the transitive resolution of the VEE Port is enabled, refer to :ref:`sdk_6_vee_port_transitivity` for more information. - When your VEE Port is available locally as an archive file (``.zip`` or ``.vde``), you can use it by declaring a file dependency in the ``build.gradle.kts`` file, with the ``microejVee`` configuration:: @@ -158,6 +155,12 @@ This is generally the case when - the VEE Port has been built locally in SDK 6, by executing the ``buildVeePort`` Gradle task on the VEE Port project. In this case, the VEE Port archive is located at ``build/veePort.zip`` in the project. + +.. warning:: + + It is recommended to :ref:`include the VEE Port project ` instead of using a file dependency to ensure that any change done + to the VEE Port project is considered when building your Application without having to manually rebuild the VEE Port. + - the VEE Port has been built and published in SDK 5. In this case, the VEE Port archive is available in an artifact repository and can be downloaded manually to be used in your Application or Library project. @@ -195,7 +198,8 @@ Resolve a VEE Port transitively .. warning:: - The transitive resolution of a VEE Port is not supported for VEE Ports built with SDK 5 or SDK 6 ``1.2.0`` or older and local VEE Ports. + The transitive resolution of a VEE Port is not supported for VEE Ports built with SDK 5 or SDK 6 ``1.2.0`` or older provided + as :ref:`module ` or :ref:`project `. While this feature is optional for now, it will be enabled by default in the next SDK 6 major version, so it is highly recommended to update your VEE Port if necessary. By default, the VEE Port is not fetched transitively by consumer projects, but starting from SDK 6 ``1.4.0``, it is possible to enable the transitivity of the VEE Port by: diff --git a/SDK6UserGuide/testProject.rst b/SDK6UserGuide/testProject.rst index cb1a462e9..14ae40544 100644 --- a/SDK6UserGuide/testProject.rst +++ b/SDK6UserGuide/testProject.rst @@ -129,9 +129,8 @@ As a summary, the rules are: .. warning:: Declaring a VEE in project dependencies only applies to the current project. - By default the transitive resolution of the VEE is disabled but you can enable it with the project property ``feature.vee.transitivity.enabled``, - refer to :ref:`sdk_6_vee_port_transitivity` for more information. - When configuring the VEE to test a Library project, it is recommended to use ``testMicroejVee``. + By default the transitive resolution of the VEE is disabled but you can enable it with the project property ``feature.vee.transitivity.enabled``. + For more information, refer to :ref:`sdk_6_vee_port_transitivity`. Create a Test Class ^^^^^^^^^^^^^^^^^^^