View source

=Developing the OpenCms core=

(This is an extension to the [http://documentation.opencms.org/opencms-documentation/extending-opencms/development-setups/ 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 the compiled OpenCms classes, inclusive a/b/c/**/*.class and d/e/f/**/*.class)
 |    +--- lib/ (contains all jar files, inclusive opencms.jar, a.b.c.jar and d.e.f.jar)
 |    \--- modulesZip (contains all modules distribution zips, inclusive a.b.c.zip and d.e.f.zip)
 +--- 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 and modules that use gwt to generate ui elements. These sources will be compiled with the gwt-compiler)
 |    |    +--- a/b/c/ (per module, the dir path is calculated from <tt>module.gwt</tt>, defined in the <tt>module.properties</tt> of the module)
 |    |    |    \--- a.b.c.gwt.xml (gwt config. <tt>a.b.c</tt> is the value of <tt>module.gwt</tt> declared in the <tt>module.properties</tt> of the module)
 |    |    \--- d/e/f/
 |    |         \--- d.e.f.gwt.xml
 |    +--- src-modules
 |    |    +--- a/b/c/**/* (sources and resources of a package without gwt code. Modules declare their packages within the <tt>module.packages</tt> property of their <tt>module.properties</tt> file.)
 |    |    \--- d/e/f/**/*
 |    \--- modules/all-modules.properties
 |         +--- a.b.c/ 
 |         |    +--- module.properties
 |         |    +--- META-INF/services/
 |         |    +--- resources/ (contains the module resources, e.g. html, css, jsps...)
 |         |    |    +--- system/modules/a.b.c
 |         |    |    |    +--- 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...)
 |         \--- d.e.f/ 
 |              +--- module.properties
 |              +--- META-INF/services/
 |              +--- resources/
 |              |    +--- system/modules/d.e.f
 |              |    |    +--- lib/**/*.jar
 |              |    |    \--- libext/**/*.jar
 |              |    \--- manifest.xml
 |              \--- static
 +--- version.properties  (external version properties file)
 +--- external-modules-altExternalStructure (priority 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.)
 |    +--- all-modules.properties (list of all external modules. If present, altExternalStructure is set to true)
 +    +--- g.h.i /
 +    |    (TODO)
 +--- 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)
      |    +--- g.h.i/ (per module. Contains the resources of the module)
      |    +--- j.k.l/
      |    \--- 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 code)
      +--- src-gwt (contains the java sources of all external 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 <tt>module</tt> 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 <tt>ext</tt> prefix. E.g.:

 project.ext.max_heap_size='1024m'