Latest revision as of 18:37, 28 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. 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)
|    \--- distributions (contains opencms.war, )
+--- opencms-core/ (opencms-core sources. The folder name is not prescribed)
|    +--- build-default.properties (config file with a list of old jar libraries for the updater)
|    +--- src/ (server, gwt-server and gwt-shared sources of the opencms core)
|    |    +--- org/opencms/main/version.properties (internal version properties file. Ignored if 'work/version.properties' exists)
|    |    \--- **/* (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/ (java service provider configuration files)
|    |    |    |    \--- **/* (additional META-INF resources)
|    |    |    +--- 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 ([optional] module additional libraries -- included in the module compilation classpath)
|    |    |    |    |    +--- libext/**/*.jar ([optional] same as 'lib'. 'lib' and 'libext' can coexist)
|    |    |    |    |    \--- **/* (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
|    |         +--- ...
|    |         .
|    |         .
|    |         .
|    +--- webapp/
|    |    +--- META-INF/MANIFEST.MF (opencms.war manifest)
|    |    +--- WEB-INF/
|    |    |    +--- classes/
|    |    |    |    +--- META-INF/persistence.xml (runtime persistence config)
|    |    |    |    +--- ehcache.xml (runtime jpa caching config)
|    |    |    |    +--- log4j.properties (runtime logging config)
|    |    |    |    \--- repository.properties (runtime cmis service config)
|    |    |    +--- opencms.tld (opencms.jar tld)
|    |    |    +--- opencms.tld (opencms.jar tld)
|    |    |    \--- web.xml (web descriptor of the opencms webapp, i.e. 'opencms.war')
|    |    +--- setup/
|    |    |    +--- database/ (database drivers)
|    |    +--- update/ (updater webapp, aka. 'opencms-upgrade-to' zip file)
|    |    +--- workplaceThemes/ (VAADIN theming. Compiled with Vaadin's Sass compiler into the 'opencms/styles.css' stylesheet)
|    |    +--- solr/ (SOLR config files)
|    |    +--- spellcheck/
|    |    +--- resources/ (additional webapp resources, e.g. toolbar.css)
|    +--- lib/jni/ (jni runtime libraries)
|    \--- doc/
|         +--- javadoc (static resources used during javadoc generation)
|         \--- documentation (outdated opencms documentation - in tex format)
+--- version.properties  ([opt] external version properties file)
|
+--- external-modules (sources of additional opencms modules, e.g. Alkacon's modules-v8. The name of this directory is defined by the value of the property 'external_directories')
|    +--- modules/ (modules resources)
|    |    +--- all-modules.properties (list of all external modules. If present, 'altExternalStructure' is set to 'false')
|    |    +--- 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)
|    |    |    +--- module.properties
|    |    |    +--- META-INF/
|    |    |    |    +--- services/ (java service provider configuration files)
|    |    |    |    \--- **/* (additional META-INF resources)
|    |    |    +--- 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  |    
|    |    |    |    +--- manifest.xml (module manifest file)
|    |    |    |    +--- system/modules/g.h.i
|    |    |    |    |    +--- lib/**/*.jar ([optional] module additional libraries -- included in the module compilation classpath)
|    |    |    |    |    +--- libext/**/*.jar ([optional] same as 'lib'. 'lib' and 'libext' can coexist)
|    |    |    |    |    +--- **/* (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)
|    |    +--- 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)
|
\--- external-modules-altExternalStructure/ (alternative file hierarchy for external modules. The name of this directory is defined by the value of the property 'external_directories'.  Notice that this directory is ignored if the file 'external-modules/modules/all-modules.properties' is present)
     +--- all-modules.properties (list of all external modules. If present, 'altExternalStructure' is set to 'true')
     +--- g.h.i /
     |    +--- module.properties
     |    +--- META-INF/
     |    |    +--- services/ (java service provider configuration files)
     |    |    \--- **/* (additional META-INF resources)
     |    +--- 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 ([optional] module additional libraries -- included in the module compilation classpath)
     |    |    |    +--- libext/**/*.jar ([optional] same as 'lib'. 'lib' and 'libext' can coexist)
     |    |    |    \--- **/* (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
          +--- ...
          .
          .
          .

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

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

build-default.properties
\--- updater.jars.remove (comma separated list of old jars that the updater will remove upon upgrade)

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

{external-modules/modules/all-modules.properties, external-modules/all-modules.properties} (if not using or if using 'altExternalStructure', respectively)
\--- modules.common.all (list of all additional module names)


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

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

opencms-core/modules/$moduleName/module.properties (compile settings for internal 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'