OpenCms Documentation/Extending OpenCms/Development setups

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. For clarity, a.b.c and d.e.f represent two internal --as opposed to external-- modules; and g.h.i and j.k.l represent two external modules. Notice that there are two possible external modules hierarchies, but the build only supports one of them. If both are present, only altExternalStructure is considered.

work/
+--- BuildCms/ (build target dir)
|    +--- classes/ (contains all --i.e., opencms core, internal modules and external modules-- compiled classes, )
|    +--- lib/ (contains all jar files, inclusive opencms.jar, a.b.c.jar, d.e.f.jar, g.h.i.jar and j.k.l.jar)
|    \--- modulesZip (contains all modules distribution zips, inclusive opencms.zip, a.b.c.zip, d.e.f.zip, g.h.i.zip and j.k.l.zip)
+--- opencms-core/ (opencms-core sources. The folder name is not prescribed)
|    +--- src/ (server, gwt-server and gwt-shared sources of the opencms core)
|    |    +--- org/opencms/main/version.properties (internal version properties file)
|    |    \--- **/* (source files)
|    +--- src-gwt/ (gwt-client code of the opencms core and internal modules. These sources will be compiled with the gwt-compiler)
|    |    +--- a/b/c/ (the path is calculated deduced from the 'module.gwt' value defined in the 'module.properties' of the module 'a.b.c')
|    |    |    +--- a.b.c.gwt.xml (gwt config of the 'a.b.c' module. The file name is deduced from the 'module.gwt' value defined in the 'module.properties' of the module 'a.b.c')
|    |    |    \--- **/*.java (additional gwt-client code)
|    |    +--- d/e/f/
|    |    |    +--- d.e.f.gwt.xml
|    |    |    \--- **/*.java (additional gwt-client code)
|    |    \--- **/*.java (additional gwt-client code, inclusive common gwt modules)
|    +--- src-modules
|    |    +--- a/b/c/**/* (server-side sources and resources of a package --no gwt code--. Each modules declares its packages within the "module.packages" property of its "module.properties" file.)
|    |    \--- d/e/f/**/*
|    \--- modules/
|         +--- all-modules.properties (list of all internal modules)
|         +--- a.b.c/ (resources of the module 'a.b.c')
|         |    +--- module.properties
|         |    +--- META-INF/services/
|         |    +--- resources/ (contains the module static resources, e.g. html, css, jsp, external js libs... Files under this folder are included in the module distribution file under the root '/' folder of the zip file preserving their folder structure)
|         |    |    +--- manifest.xml (opencms module definition. Defines also dependencies on other modules required during compilation)
|         |    |    +--- system/modules/a.b.c
|         |    |    |    +--- lib/**/*.jar (module libraries -- used during module compilation) - XXX: AG - Really? I have to double-check this...
|         |    |    |    +--- libext/**/*.jar (same as 'lib')
|         |    |    |    \--- **/* (additional module resources)
|         |    |    \--- **/* (additional module resources)
|         |    \--- static (optional. If present, contains e.g. css and font files for gwt, 3rd party html and js resources of 'tinymce' and 'codemirror' modules. These files are packaged under the '/OPENCMS' folder in the zip distribution file, preserving their folder structure. These will be served from an opencms URL constructed for this purpose)
|         \--- d.e.f/ (same structure as 'a.b.c/')
|              +--- module.properties
|              +--- ...
|              .
|              .
|              .
+--- version.properties  (external version properties file)
|
+--- external-modules-altExternalStructure/ (file hierarchy for external modules. The name of this directory is not fixed. OpenCms looks for this directory based on the property value of external_directories. This folder has priority over the non altExternalStructure folder)
|    +--- all-modules.properties (list of all external modules. If present, altExternalStructure is set to true)
|    +--- g.h.i /
|    |    +--- module.properties
|    |    +--- src-gwt/ (gwt client code of the module)
|    |    +--- src/ (non-gwt, gwt-server and gwt-shared code of the module)
|    |    +--- resources/ (resources of the module. Files under this folder are included in the module distribution file under the root '/' folder of the zip file preserving their folder structure)
|    |    |    +--- manifest.xml (module manifest file)
|    |    |    +--- system/modules/g.h.i
|    |    |    |    +--- lib/**/*.jar
|    |    |    |    +--- libext/**/*.jar
|    |    |    |    \--- **/* (additional module resources)
|    |    |    \--- **/* (additional module resources)
|    |    \--- static/ (optional. If present, contains static resources, e.g. gwt static css files. These files are packaged under the /OPENCMS folder in the zip distribution file, preserving their folder structure. These will be served from an opencms URL constructed for this purpose)
|    \--- j.k.l/ (same structure as 'g.h.i/')
|         +--- module.properties
|         +--- ...
|         .
|         .
|         .
+--- external-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. Notice that this directory is ignored if external-modules-altExternalStructure/all-modules.properties is present)
     +--- modules/ (modules resources)
     |    +--- all-modules.properties (list of all external modules)
     |    +--- g.h.i/ (resources of the module. Files under this folder are included in the module distribution file under the root '/' folder of the zip file preserving their folder structure)
     |    |    +--- manifest.xml (module manifest file)
     |    |    +--- system/modules/g.h.i
     |    |    |    +--- lib/**/*.jar
     |    |    |    +--- libext/**/*.jar
     |    |    |    \--- **/* (additional module resources)
     |    |    \--- **/* (additional module resources)
     |    +--- j.k.l/ (same structure as 'g.h.i/')
     |         +--- module.properties
     |         +--- ...
     |         .
     |         .
     |         .
     +--- src (server, gwt-server and gwt-shared sources of the the external modules that will be compiled with javac)
     +--- src-gwt (gwt-client code of the external modules. These sources will be compiled with the gwt-compiler)
     \--- all-modules.properties (list of all external modules if modules/all-modules.properties not available) XXX: AG - Really? I have to double-check...

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'