Revision as of 14:24, 24 July 2017

Developing the OpenCms core

(This is an extension to the official documentation page)

With the default configuration, the gradle build script assumes the following directory hierarchy:

work/
+--- BuildCms/ (build target dir)
|    +--- classes (contains the compiled OpenCms classes)
|    \--- modulesZip (contains all modules distribution zips)
+--- opencms-core/ (opencms-core sources)
|    +--- src/ (OpenCms main sources)
|    |    \----org/opencms/main/version.properties (internal version properties file)
|    +--- src-gwt/ (contains the java sources of the OpenCms core modules that use gwt to generate ui elements. These sources will be compiled with the gwt-compiler)
|    |    \--- $gwtModulePath/ (per module, gwtModulePath is calculated from module.gwt, defined in the module.properties of the module)
|    |         \--- $gwtModuleName.gwt.xml (gwt config. gwtModuleName is the module.gwt defined in the module.properties of the module)
|    +--- src-modules
|    |    \--- $packagePath/**/* (sources and resources of a package. Modules declare their packages within the module.packages property of their module.properties file)
|    \--- modules/all-modules.properties
|         \--- $moduleName/ (per module)
|              +--- module.properties
|              +--- META-INF/services/
|              +--- resources/ (contains the module resources, e.g. html, css, jsps...)
|              |    +--- system/modules/$moduleName
|              |    |    +--- lib/**/*.jar (module libraries -- used during compilation of module)
|              |    |    \--- libext/**/*.jar (same as 'lib')
|              |    \--- manifest.xml (OpenCms module definition. Defines also dependencies on other modules that will be used during compilation)
|              \--- static (e.g. css and font files for gwt, 3rd party html and js resources of tinymce and codemirror modules...)
+--- version.properties  (external version properties file)
+--- extra-modules (sources of additional opencms modules, e.g. Alkacon's modules-v8. The name of this directory is not fixed.
     |              OpenCms looks for this directory based on the property value of external_directories.)
     +--- modules/ (modules resources)
     |    +--- $moduleName/ (per module. Contains the resources of the module)
     |    \--- all-modules.properties (list of all external modules)
     +--- src (contains the java sources of all extra modules that must be compiled with javac --that is, no gwt-ui code)
     +--- src-gwt (contains the java sources of all extra modules that use gwt to generate ui elements. These sources will be compiled with the gwt-compiler)
     \--- all-modules.properties (list of all external modules if modules/all-modules.properties not available)

The gradle build script accesses the following configuration files (some relevant properties are shown):

version.properties
\--- version.number (version information)

opencms-core/modules/all-modules.properties
\--- modules.common.all (list of all module names)

extra-modules/modules/all-modules.properties
\--- modules.common.all (list of all additional module names)

extra-modules/all-modules.properties (if extra-modules/modules/all-modules.properties not available)
\--- modules.common.all (list of all additional module names)

opencms-core/src-gwt/org/opencms/GwtBaseCommon.gwt.xml (tune to skip unnecessary builds)
+--- locale
\--- use.agent

opencms-core/webapp/WEB-INF/classes/log4j.properties (default logging settings)

opencms-core/modules/$moduleName/module.properties (compile settings for module $moduleName)
+--- module.packages (comma separated list of packages to include in the compilation)
\--- module.gwt [optional] (name of the associated gwt module, if any. This is the module of the gwt-compiler command line)

The gradle build scripts supports the following properties (defaults are shown, if defined):

additional_repositories (semicolon-separated list the urls of maven repositories)
max_heap_size: 1024m (maximum heap size for the tasks workplaceTheme, gwt_* and test*)
external_directories (path to an additional gradle project with OpenCms modules, i.e., there is a $external_directories/modules/all-modules.properties file)
tomcat_update_target (path to the lib dir of the deployed opencms webapp, e.g. /var/lib/tomcat/webapps/opencms/WEB-INF/lib)
noVersion (if set, sets the distribution version to the empty string)
module_copy_target (if set to an existing filepath, copies the distributables to that path)
testCaseToRun (for the testSingle task, path to the test cases, e.g. 'org/opencms/main/TestCmsSystemInfo*')
publish_repository (if set, defines a new uploadArchives tasks that allows the upload of artifacts to an external repository. Notice that the repository could be the file system, e.g. 'file:///$PWD/target/install')
publish_user, publish_password (if publish_repository is set, these variables must also be set and define the credentials required to upload artifacts to $publish_repository)
skip_javadoc: unset (if set to true, javadoc generation is skipped)

Note.- Inside the gradle script, properties can be defined using the ext prefix. E.g.:

project.ext.max_heap_size='1024m'