Revision as of 09:53, 10 March 2015

Note: this is work in progress!

Building opencms-core

Note: This build process has been tested for Java versions 7 and 8, and Gradle versions 1.8 and 2.1.

Checkout, fix if necessary and install the Alkacon Acacia Editor

Both opencms-core ms_9_4_7 and the com.alkacon.opencms.v8.calendar module depend on the Alkacon online editor Acacia. This dependency has not yet been uploaded to the maven repository, so you have to build and install it yourself.

Checkout the version tagged opencms_9_4_7 of the acacia-editor:

pushd ~/src
git clone https://github.com/alkacon/acacia-editor.git -b opencms_9_4_7 acacia-editor-opencms_9.4.7
cd acacia-editor-opencms_9.4.7

If you're using Java 8, apply the patch to work around the javadocs:

git fetch origin pull/4/head
git merge FETCH_HEAD

And install the jars:

gradle install
popd

Checkout the sources of the ms_9_4_7 tag^{1, 2, 3}

git clone https://github.com/alkacon/opencms-core.git -b ms_9_4_7 opencms-core-ms_9.4.7

After checkout, cd into the new directory

pushd opencms-core-ms_9.4.7

Adjust if necessary the versioning configuration

Edit the file src/org/opencms/main/version.properties or edit and execute the script create_version_properties.sh

Execute the gradle bindist task

gradle bindist

Tip for developers: Gwt generates code for all the possible permutations of the supported languages and browsers. This compilation takes a significant part of the complete build time. During development builds you could find useful to generate the corresponding gwt code only for a language and a browser restricting the value of the properties locale and user.agent to only one value in the file src-gwt/org/opencms/GwtBase.gwt.xml.

Once this task is finished, you should have (among others) a distributions directory under your (in the property build_directory of the file gradle.properties) configured build directory, containing the distributable opencms-[version].zip and the deployable opencms.war.

Install the jars in your local maven repository if necessary^{4, 5}

If you want to also build the opencms oamp, v8 or v7 modules, you also need to install in your local maven repository the corresponding jars

gradle install

Building alkacom-oamp

This section is unfinished, as I haven't been able to compile the sources without reverting some commits. (For me, not a valid approach.)

Checkout the sources of the 9_5_x branch⁶

popd
git clone https://github.com/alkacon/alkacon-oamp.git -b branch_9_5_x alkacon-oamp-9.5.x

After checkout, cd into the new directory

pushd alkacon-oamp-9.5.x

and edit if necessary the build properties to match versions (see note 5).

Patch the code

If you are using Gradle 2.0+, you'll need the patch:

• #30 (See also the thread OpenCms 9.0.1 ready for download)

And if you are using Java 8+, you'll also need patches:

• #34
• #35

Unfortunatelly, the code in this repository is not synchronized with the changes in `opencms-core`, so you need some more patches:

• #39
• #41
• #43

To apply the patches, fetch them and merge them into your working branch. For example, to apply patch 30:

git fetch origin pull/30/head

# "--no-edit" to accept default commit message (batch mode)
git merge --no-edit -s recursive -X ignore-space-at-eol FETCH_HEAD

Provisional fixes

There have been some changes in opencms-core without corresponding updates in alkacon-oamp. I have created provisional branches to fix these problems, but I didn't published them as pull-request because they only contain dummy implementations.

You can still merge them without adding a remote repository:

git fetch https://github.com/gallardo/alkacon-oamp.git workaround_31

# "--no-edit" to accept default commit message (batch mode)
git merge --no-edit -s recursive -X ignore-space-at-eol FETCH_HEAD

Last workaround

I couldn't build the module `com.alkacon.opencms.v8.calendar` without reverting it to the tagged version calendar_2.0.0 (from 2012-06-21). If you are willing to sacrifice the last commits in this module:

rm -r com.alkacon.opencms.v8.calendar
git checkout calendar_2.0.0 -- com.alkacon.opencms.v8.calendar

Execute the gradle bindist task

Now you should be able to build the distributable files:

gradle bindist

Notes

1. Checking out the build tagged build_9_0_1 and executing gradle fails with the following message (see post OpenCms 9.0.1 ready for download):

> Could not find property 'distribution' on configuration ':compile'.

2. In the branch branch_9_0_x this issue is fixed, but there is still an ISO encoded file test/org/opencms/search/extractors/TestMsPowerPointExtraction.java that breaks the javadocs:

[...]
:javadocTest
/home/myuser/src/opencms-9.0.x/opencms-core/test/org/opencms/search/extractors/TestMsPowerPointExtraction.java:93: error: unmappable character for encoding UTF8
        // this is "�������"
                    ^
/home/myuser/src/opencms-9.0.x/opencms-core/test/org/opencms/search/extractors/TestMsPowerPointExtraction.java:93: error: unmappable character for encoding UTF8
       // this is "�������"
                    ^
[...]
14 errors
:javadocTest FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':javadocTest'.
> Javadoc generation failed.

The commit 89e10779 fixes the encoding, but it hasn't made it into branch_9_0_x. Currently (2014-10-08) it is only available in tag ms_9_4_7 and branch branch_9_5_x.

3. For the sake of stability, I favor tagged versions over branches, that is tag ms_9_4_7 over branch branch_9_5_x. (There is unfortunately no tags for the branch_9_5 branch yet.)

4. The current javadocs are broken and when using Java 8+, gradle fails with the following message:

[...]
100 errors
100 warnings
:javadoc FAILED

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':javadoc'.
[...]

I have written a pull-request to work around this issue: https://github.com/alkacon/opencms-core/pull/278. Please note that this pull is for the branch branch_9_5_x. Be warned that merging it into a branch based upon the tag ms_9_4_7 will also merge all the changes between commits ms_9_4_7..branch_9_5_x.

That is, if you want to pull the whole changes (not recommended, as alkacon-oamp is as for today not yet compatible with opencms-core branch_9_5_x):

git fetch origin pull/278/head
git merge FETCH_HEAD

If you only want the changes from this patch (recommended and tested):

git fetch origin pull/278/head
git cherry-pick origin/branch_9_5_x..FETCH_HEAD

5. You need to match the version of the generated opencms-core artifacts to the version of the alkacon-oamp dependencies. Since commit 89e10779 (from 2014-04.02, already in branch_9_5_x), the property version.number in the file opencms-core/src/org/opencms/main/version.properties defines the versions of the opencms-core artifacts. The property opencms_version of the file alkacon-oamp/gradle.properties declares the version of the dependencies:

# Static version information file
#
# You should set this to something meaningful before you build.
version.number=9.5.x
version.id=Manual build
build.number=(not set)
build.date=(not set)
nicename.build.number=Build Number
nicename.build.date=Build Date
# This has no nice name on purpose (for test cases)
build.info=Static version file

build_directory=../../BuildOAMP
opencms_version=9.5.x
java_target_version=1.6
max_heap_size=1024m

# all available modules
modules_oamp_all=\
com.alkacon.opencms.commons,\
com.alkacon.opencms.calendar,\
com.alkacon.opencms.documentcenter,\
[...]

6. Unfortunatelly, Alkacon has not tagged this repository yet for opencms 9+. The repository has been apparently tagged on a component basis, independently of the opencms-core development. This makes difficult to pick any of the existing tags without knowing beforehand if all the components are in a sane and stable state.

This instructions are based on the latest revision as for 2014-10-16: #98dffd7. To match your version to this one, after cloning the repository you can also use this commit as basis:

git checkout 98dffd71bdfe51f95d9b1a39fda3c7084c08bb5f