document Kernel transitivity

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:

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 

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 <sdk_6_vee_port_transitivity>` or 
+a :ref:`Kernel <sdk_6_kernel_transitivity>`. 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 <sdk_6_testsuite_vee_configuration>`, 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 <sdk_6_select_veeport_local_directory>` or 
+   :ref:`as an archive <sdk_6_select_veeport_local_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 <https://docs.gradle.org/current/userguide/java_library_plugin.html#sec:java_library_separation>`__.
+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 <sdk_6_testsuite_vee_configuration>`, 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 <sdk_6_select_local_kernel>`.
+
+..
+   | 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.

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 <sdk_6_vee_port_transitivity>` 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 <sdk_6_vee_port_transitivity>` 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 

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.
 

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 <https://docs.gradle.org/current/userguide/composite_builds.html>`_ 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 <sdk_6_select_kernel_outside_multi-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 <sdk_6_select_kernel_module>` or :ref:`project <sdk_6_select_kernel_in_multiproject>`.
+   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