Skip to content

Latest commit

 

History

History
221 lines (156 loc) · 8.21 KB

Plugin-sap.commerce.build.md

File metadata and controls

221 lines (156 loc) · 8.21 KB
Raw

Plugin sap.commerce.build

The goal for this plugin is to automate the most common steps when setting up a SAP Commerce development environment and allows you to call the platform ant build as a Gradle task (in your script, or from the command line).

The plugin is compatible with Gradle versions > 5.6.4.

Modes

The plugin can operate in standard mode, driven by the configuration, or in CCv2 mode.

In CCv2 mode, part of the configuration is ignored and replaced by the settings in the manifest.json.

CCv2 mode is activated when also using the sap.commerce.build.ccv2 in the same build configuration.

Configuration

The following example shows the full Domain Specific Language (DSL) with all default options and pre-configured dependencies.

hybris {
    //SAP Commerce version to use (ignored in CCv2 mode)
    version = "2205.0"
    
    //SAP Commerce Integration Extension Pack version to use (ignored in CCv2 mode), optional
    intExtPackVersion = "2205.1"
    
    //What files should be deleted when cleaning up the platform?
    cleanGlob = "glob:**hybris/bin/{ext-**,platform**}"
    
    //What should be unpacked from the platform zip files?
    bootstrapInclude = [
      "hybris/**"
    ]
    
    //What should excluded when unpacking?
    //  The default value is a npm package folder that includes UTF-8 filenames,
    //  which lead to problems on linux
    bootstrapExclude = [
      "hybris/bin/ext-content/npmancillary/resources/npm/node_modules/http-server/node_modules/ecstatic/test/**"
    ]
   
   //Default task dependencies for all tasks generated by the hybris ant rule
   antTaskDependencies = []
   
   //Optional mapping of preview version to patch level.
   // manifest.json requires the Commerce Suite version in the format 2211.8, while the platform build.number
   // uses 2211.FP1. This mapping allows the plugin to convert between the two formats. 
   previewToPatchLevel = [
      "2211.FP0": 4,
      "2211.FP1": 8
   ]
   
   //Control the sparse platform bootstrap.
   //  When enabled, the commerce extensions are extracted from the distribution zip on a as-needed basis.
   //  Only extensions that are actually used in the project (either directly listed in the localextensions.xml or
   //  required by other extensions) are extracted.
   //  The platform itself is always extracted.
   //  When this mode is enabled, the bootstrapInclude configuration property is ignored.
   sparseBootstrap {
      // default is disabled
      enabled = true
      // set of extensions that are always extracted, default is an empty set
      alwaysIncluded = [
         "yempty",
         "yocc",
         "ybackoffice"
      ]
   }
}

dependencies {
    //SAP Commerce Platform Dependencies.
    //  Define zip file dependencies that are unpacked into the project root folder.
    //  You can define more than one zip file to unpack.
    //  `bootstrapInclude` and `bootstrapExclude` define what is unpacked.
    //  "de.hybris.platform:hybris-commerce-suite:${hybris.version}@zip" is added as default dependency
    //  when the plugin is not in CCV2 mode.
    //  "de.hybris.platform:hybris-commerce-integrations:${hybris.intExtPackVersion}@zip" is added as default dependency
    //  when the plugin is not in CCV2 mode, if intExtPackVersion is defined.
    hybrisPlatform "de.hybris.platform:hybris-commerce-suite:${hybris.version.get()}@zip"
    hybrisPlatform "de.hybris.platform:hybris-commerce-integrations:${hybris.intExtPackVersion.get()}@zip"
    
    //JDBC Drivers. 
    //  Automatically downloaded and configured during bootstrap, if a dependency is configured.
    //  The plugin does not provide defaults!
    dbDriver <NO DEFAULT>
}

Tasks

The plugin defines the following tasks

bootstrapPlatform

Bootstraps the configured platform version with the configured DB drivers.

This means the following:

  1. if there is a version mismatch between the version defined in the build.gradle and the version present in hybris/bin/platform/build.number: clean the hybris artifacts from the project directory using hybris.cleanGlob
  2. Unpack all zip files defined for the hybrisPlatform dependency using hybris.bootstrapInclude and hybris.bootstrapExclude to limit the files.
  3. Download all dbDriver dependencies into hybris/bin/platform/lib/dbdriver
  4. Touch hybris/bin/platform/lib/dbdriver/.lastupdate (this stops the platform build from running maven to fetch drivers)

The plugin uses the following default artifact coordinates to resolve the platform zip:

groupId: de.hybris.platform
artifactId: hybris-commerce-suite
versionId: ${hybris.version}
type: zip

You can override this default with the hybrisPlatform dependency in your Gradle build script.

Added in 3.9.0: Sparse platform bootstrap. When this is enabled in configuration, only the required extensions are extracted from the distribution and the hybris.bootstrapInclude is ignored.

cleanPlatform

Deletes the hybris platform folders (all files/folders matching hybris.cleanGlob)

What is a Glob?

createDefaultConfig

Launches hybris build to create the standard developer config folder, if no config folder is present

removeUnusedExtensions

⚠️ Deprecated in 4.0.0. Use sparseBootstrap instead ⚠️

Removes all extensions that are not used by the current project (either directly or indirectly). This helps developers save disk space if they juggle multiple projects.

Custom extensions (i.e. extensions in hybris/bin/custom) are never removed

To get the full platform back, bootstrap it from scratch (gradle cleanPlatform bootstrapPlatform)

Task Types

The plugin defines a custom task type you can use in your build script to interact with the normal hybris build

mpern.sap.commerce.build.tasks.HybrisAntTask

This task type allows you to define a hybris ant target as Gradle task.

Under the hood it's a pre-configured JavaExec task

Added in 3.7.0: Lazy configuration of antProperties plus fallbackAntProperties for fallbacks if something is not configured during a particular Gradle run.

Example:

task unitTests(type: mpern.sap.commerce.build.tasks.HybrisAntTask) {
    //provide ant target name as argument
    args("unittests")
    
    //everything you define with -D... when calling ant you can define via antProperty
    antProperty("testclasses.extensions", "training")
    antProperty("testclasses.suppress.junit.tenant", "true")
    
    //we can also call other ant targets by prefexing the target name with `y`
    //because the plugin defines a task rule (see below)
    dependsOn tasks.getByPath("ybuild")
}

New in 4.0.0: You can configure additional ant properties on the command line, e.g.

./gradlew ybuild --antProperty=build.parallel=true --antProperty=foo.bar=false

mpern.sap.commerce.build.tasks.SupportPortalDownload

Deprecated with v2.1.1; Removed with v3.0.0; Check the FAQ

Task Rules

For convenience, the plugin also defines task rule that allows you to call any ant target directly from the Gradle command line or from other tasks

Hybris Ant Rule

Pattern: y<target>: Run hybris ant <target>

The rule maps the called task name to the ant target and preconfigures a HybrisAntTask to execute.

Task Ordering

Warning Gradle does not know the proper order for hybris ant targets. The plugin configures sane defaults for clean, build, all and production, but for other targets you have to configure the proper order yourself.

For example inbuild.gradle:

tasks.named("ycustomtarget").configure{ mustRunAfter("yall") }

While it is possible to import an ant build into Gradle to solve this issue, I decided against it as the hybris build is very complex and slows down Gradle too much.

Task Dependencies

All tasks generated by this rule have all items in hybris.antTaskDependencies as task dependencies .

For more fine-grained control, you can define the task dependencies in your Gradle build script per task, e.g.

tasks.named("yall").configure {
    dependsOn("bootstrapPlatform")
}