English
资源说明：Jahia CMS
==============================================================================
README FOR JAHIA SOURCE CODE
==============================================================================
All source code, binaries and documentation is copyrighted (c) 2002-2011 by
Jahia Solutions Group SA. All Rights Reserved.
INTRODUCTION
------------------------------------------------------------------------------
Welcome to Jahia's source code! This code is provided under the Jahia Source
Code License Agreement. You must comply to the agreement before using this
code in any way, including reading it. Sorry for the mumble jumbo but there
are people trying to make a living while producing this code and would like
to bring more so it helps if people play fair :)
USING THIS SOURCE CODE (QUICKSTART)
------------------------------------------------------------------------------
Requirements:
- JDK 1.5 or later
- Maven 2.1 / 3.x
- Subversion client (for Windows at http://www.collab.net/downloads/subversion/
for Mac OS X from http://www.finkproject.org/ or Xcode tools, under
Linux install a subversion client from your package repository). Basically,
you need to have an "svn" command available in your PATH so that the build
system can calculate the build number
- (Optional) JetBrains IntelliJ IDEA 7.0.3 or later
Here is quick start steps to use this source code:
1. Make sure you have all the above requirements, especially the Subversion
client!
2. Code to checkout:
http://subversion.jahia.org/svn/jahia/trunk/
For more information, please check the template developer guide.
3. Download and Install Maven 3.x or 2.x (http://maven.apache.org), and set an
M2_HOME environment variable pointing at the installation
directory. Put M2_HOME/bin folder in path. Also increase the
memory for Maven by setting the following environment variable:
MAVEN_OPTS=-Xmx1024m
4. Download and Install a Java JDK (http://www.oracle.com/technetwork/java/javase/downloads/index.html).
Configure the JDK by installing a JAVA_HOME environment variable pointing to it's
installation directory.
- Under Windows:
right-click "My Computer", select "Properties", "Advanced",
"Environment", add a variable to the user or system settings with
the following value: name=JAVA_HOME, value=YOUR_PATH_TO_THE_JDK
where YOUR_PATH_TO_THE_JDK could be something like
C:\Java\jdk1.6.0_24 if you've installed JDK 1.6.0 update 24.
- Under Linux:
Add the following like to the /etc/profile configuration file
(close for example to where the PATH is declared):
JAVA_HOME=YOUR_PATH_TO_THE_JDK
You could also add this environment variable to your
~/bash_profile.
- Other unix systems:
Basically the same as under Linux, set the environement variable
JAVA_HOME to point to your JDK installation.
5. Copy the settings.example.xml file into ${USER_HOME}/.m2 directory, renaming
it to settings.xml, and modify it to your environment.
As there are problems with JSP compilation on path with spaces on Windows environments, it is
recommended you specify a default location for your local repository
that DOESN'T CONTAIN ANY SPACES IN THE PATH, for example:
C:/development/m2repository
6. When you use a new Tomcat server make sure you give it enough memory and adjust its options.
This can be increase by editing bin/catalina.sh and add the following lines:
CATALINA_OPTS="$CATALINA_OPTS -Xms1024m -Xmx1024m -Djava.awt.headless=true -XX:MaxPermSize=256m -server -Dhibernate.jdbc.use_streams_for_binary=true -verbose:gc"
export CATALINA_OPTS
CATALINA_PID=/tmp/jahia-6.5.pid
export CATALINA_PID
before the line
# OS specific support.
On Windows systems, edit the bin\catalina.bat file and add:
set CATALINA_OPTS=%CATALINA_OPTS% -Dsun.io.useCanonCaches=false -Xms1024m -Xmx1024m -XX:MaxPermSize=256m -server -Dhibernate.jdbc.use_streams_for_binary=true -verbose:gc
before the line
rem Guess CATALINA_HOME if not defined
If using embedded Derby database, please specify the correct Derby home folder in the
Tomcat startup options by adding into bin/catalina.sh:
CATALINA_OPTS="$CATALINA_OPTS -Dderby.system.home=$CATALINA_HOME/webapps/ROOT/WEB-INF/var/dbdata"
export CATALINA_OPTS
on Windows by adding into bin\catalina.bat:
set CATALINA_OPTS=%CATALINA_OPTS% -Dderby.system.home=%CATALINA_HOME%\webapps\ROOT\WEB-INF\var\dbdata
7. In the main directory, type:
mvn install jahia:deploy jahia:configure
This should compile and deploy into your local repository all of Jahia, deploy and install everything in the
application server configured in your settings.xml file.
An purely indicative time of initial compilation time (including all
dependency download) is 16 minutes. A "mvn clean install" on the same
machine takes 2 minutes 40 seconds. These times do not include JSP or
GWT compilation.
8. Point your browser to http://localhost:8080/
Default root password is root1234
9. Create your first virtual site and enjoy.
Using IDEs
------------------------------------------------------------------------------
IDEA:
1. IDEA has direct support for Maven 2, so you can simply open the project
using the IDE.
Here are the steps to create the new project:
- Open File -> New Project ...
- Select Import project from external model
- Click Next
- Select Maven
- Click Next
- Select directory where source was checked out and check the box
named "Automatically synchronize maven structure on startup"
- It should find just one project org.jahia.server:jahia-root
- Click next
- For the project name you can leave the default
- Click finish
If you have trouble with the above procedure, you can also generate
the IDEA project structure using the Maven 2 IDEA plugin this way:
mvn idea
You can find the plugin documentation here:
http://maven.apache.org/plugins/maven-idea-plugin/
Eclipse:
1. Add a new 'M2_REPO' classpath variable in Eclipse, pointing to your
Maven 2 repository folder (either using Maven or manually):
a) Using Maven: execute:
mvn -Declipse.workspace= eclipse:add-maven-repo
where is the path to your Eclipse workspace
b) Manually: in Eclipse open
Window / Preferences -> Java -> Build Path -> Classpath Variables.
Click on 'New...'
and enter M2_REPO as a name of the variable and full path to your
Maven 2 repository as path value
2. In the Jahia root folder execute the following command:
mvn eclipse:eclipse
This will generate '.project' and '.classpath' files for the seven
projects in Jahia (jackrabbit-core-ext, jackrabbit-server-ext,
jahia-api, jahia-ear, jahia-impl, jahia-war, etc.)
3. Open Eclipse and use import 'Existing Projects into Workspace'.
Using 'Browse...' select the Jahia root folder. A list of available
projects will be shown. Import projects into the workspace.
Setup Maven deployment configuration
------------------------------------------------------------------------------
In order to be able to deploy to the Jahia Maven repository, you must have setup a public/private
key pair in your settings.xml file. In order to do this you must first generate a public/private
key pair if you don't have one.
In order to do deployments to the maven repository, you need to have a public/private key pair setup on
your machine and setup the correct authorization on the remote machine.
1. ssh-keygen -b 2048 -t rsa
* If you want the key to be used in an automated setting, use an empty passphrase when the program asks for it (i.e., hit enter at the prompt without typing anything else first).
2. Append the public key (id_rsa.pub) to your /.ssh/authorized_keys file on the remote machine. If you don't already have the directory or the file, first create the /.ssh/ directory, then copy the id_rsa.pub file to the remote machine, and finally rename it to /.ssh/authorized_keys.
3. Add the following information in your ${USER_HOME}/.m2/settings.xml file :
jahiaRepository
YOUR_USERNAME
${user.home}/.ssh/id_rsa
Deploying new JARs to maven.jahia.org
------------------------------------------------------------------------------
Requirements:
- on Windows: putty SSH applications (puttygen.exe)
- on Linux/Mac OS X/UNIX: OpenSSH for JAR deployment to maven.jahia.org
First check if the JAR is not available by googling for it (ex using the
command:
maven2 YOURJAR
as a search criteria). It is better to use a public resource, which will
probably include transitive dependencies.
You should always remember to send your new JARs to the maven.jahia.org
repository. Here is the procedure on how to do it.
1. Generate an OpenSSH public/private DSA key pair (on Windows this can be
done with puttygen and export to OpenSSH format)
2. Send the public key to the Jahia IT admin and ask for it to be
installed on the maven.jahia.org server
3. Use the mvndeploy.bat file on Windows to deploy your JAR, or use the
equivalent command line. Also, if you have a POM for your JAR that
includes dependencies this is a better than letter Maven generate one
for you.
Compiling a single GWT module
------------------------------------------------------------------------------
GWT compilation of modules is quite a heavy operation, and it may require a
lot of time to build an entire build. For this, we have added the possibility
to only compile a single module by using command line parameters. The syntax
is the following:
mvn MAVEN_GOAL -DsingleModule=true -DsingleModuleName=MODULE_NAME
and an example would be:
mvn install -DsingleModule=true -DsingleModuleName=org.jahia.ajax.gwt.module.edit.Edit
In order to make things even easier, we have provided script and batch files
for UNIX and Windows, called single_module.sh and single_module.bat. With
these the above example becomes:
./single_module.sh install org.jahia.ajax.gwt.module.edit.Edit
This executes in 1 minute instead of 20!
Also, if you just don't care about GWT compilation, you can single call:
mvn install -DsingleModule=true
This will compile only the org.jahia.ajax.gwt.module.edit.Edit
module. You can also achieve the same result with the simple call:
./single_module.sh
This will call the install goal and generate the Edit module. If you still
want to specify a Maven goal, you can simply do just that:
./single_module.sh compile
Developing and running unit tests
------------------------------------------------------------------------------
Tests are all packaged in the test module. They are intended to be executed in a live jahia context, and are able to
test any stuff on the server side, from a simple DAO to a high end service.
Adding a new test simply consist in adding a TestCase class in the test module. All tests commited in the test module
will be executed automatically after each build on the Bamboo server.
To manually run the tests:
- Go to the test module, execute:
mvn install jahia:deploy
( note that class hotswap is also working for this module, test code change won't require a jahia restart )
- Startup your jahia
- Execute:
All tests: mvn jahia:test surefire-report:report-only
or one single test: mvn -Dtest=org.jahia.services.stuff.MyTest jahia:test surefire-report:report-only
The plugin will use the url set in the parameter " " in your settings.xml file
- Open the file target/site/surefire-report.html and look at the result.
- To execute selenium tests, server selenium is require. You have to download selenium RC here: http://seleniumhq.org/download/
This tests are configure to be run through http://localhost:8080/cms
Code coverage generation
------------------------------------------------------------------------------
Jahia's maven project structure is now integrated with the Atlassian Clover
reporting tool. The new "code-coverage" profile must be activated in your
settings.xml. You must also add the following plugin group in the same file:
com.atlassian.maven.plugins
In your Tomcat, add to the shared library directory the clover*.jar that you
should find in your Maven repository in the
.m2/repository/com/cenqua/clover/clover/2.4.2
directory. Deploy to tomcat/shared/lib under Tomcat 5.x and under tomcat/lib
under Tomcat 6.x.
Then do from root:
mvn clean install -P testJahia
This will deploy jahia,start your tomcat and stop it, and then undeploy jahia.
The resulting report will be generated in target/site/clover/ for clover and in
the file target/site/surefire-report.html and look at the test result.
WARNING: Clover will instrument your code in your local repository, meaning
that the JARs will contain code to analyse the code's behavior and also
hardcoded paths to store the analysis results. So you should NEVER upload
instrumented JARs to the remote repository, because they will simply not work.
It might be a good idea, when compiling for code coverage, to use an
alternate remote repository. You can do this by using the following command
line argument:
-Dmaven.repo.local=/home/myusername/.m2/repository-for-clover
Troubleshooting
------------------------------------------------------------------------------
If you encounter javascript errors, java exceptions related to an AJAX class,
or any other engine GUI problem, it is likely that you have upgraded your
Jahia server without emptying the browsers'cache. Before requesting support,
try the following:
1. Empty the browser cache using the browsers options. The option to empty the cache
is usually located in the "privacy options".
2. Close all browsers windows.
3. Restart your browser and try again. If the problem persists, please contact us.
Version numbering
------------------------------------------------------------------------------
We following the following convention for version numbering :
MAJOR.MINOR.SERVICEPACK.PATCH
Please respect this when performing releases so that all the parsing code
works correctly.
Performing a release with the Maven Release plugin
------------------------------------------------------------------------------
It is now possible to use the Maven Release plugin to automate the build of
a release. This will change all the pom.xml versions, commit the change,
compile the project, create a tag and then change all the pom.xml back to
a SNAPSHOT version and commit again.
But before we do this, there are a few changes we must do to the Jahia
project :
1. Create the adequate license.xml files
2. Commit the changes and then use the Maven Release Plugin (see below) to
perform the rest of the release
3. It is recommended also to do all the following steps on a clean checkout of
the codebase, as in your working directory you might have local changes or
IDE project files that will conflict with proper preparation. You can for example
checkout the project like this :
svn checkout https://username@svnserver/svn/jahia/trunk
You will probably want to also test a commit to make sure you have setup everything
properly before running the Maven release plugin
4a. If you're not familiar with the release plugin or want to simply double-check things, you can perform first
a dry run with the command :
mvn -DdryRun release:prepare -P installer,windows-installer,qa-build,test
Once it is completed reset the project by using the command :
mvn release:clean -P installer,windows-installer,qa-build,test
4b. You can perform all this with the following command line :
mvn release:prepare -P installer,windows-installer,qa-build,test
When asked for versions, here is an example :
There are still some remaining snapshot dependencies.
: Do you want to resolve them now? (yes/no) no: : yes
Dependency type to resolve,: specify the selection number ( 0:All 1:Project Dependencies 2:Plugins 3:Reports 4:Extensions ): (0/1/2/3) 1: :
What is the release version for "Jahia Project Root"? (org.jahia.server:jahia-root) 6.5: : 6.5-BETA2
What is SCM release tag or label for "Jahia Project Root"? (org.jahia.server:jahia-root) jahia-root-6.5-BETA2: : JAHIA_6_5_BETA2
What is the new development version for "Jahia Project Root"? (org.jahia.server:jahia-root) 6.5-BETA3-SNAPSHOT: : 6.5-SNAPSHOT
5. Test a staging of the release by doing the following :
mvn -DstagingRepository=stagingDir::default::file:///Users/loom/java/temp release:stage
6. Once everything looks right, you can perform the release by doing :
mvn release:perform
This step requires that you have correctly setup deployment to the Maven repository
as described in this README in the section called "Deploying new JARs to maven.jahia.org"
Tips :
- If for some reason you need to start again you can use the release:clean or
if something was already committed, prepare a rollback with release:rollback
- If you want to perform staging on a specific tag, here is an example :
mvn -DconnectionUrl=scm:svn:https://devtools.jahia.com/svn/jahia/tags/JAHIA_6_5_BETA2 -DstagingRepository=stagingDir::default::file:///Users/loom/java/temp release:stage
- If you're running of these an the Bamboo server, make sure you use the alternate local repository with the following
command line option : -Dmaven.repo.local=/home/bamboo/.m2/repository-for-package
本源码包内暂不包含可直接显示的源代码文件，请下载源码包。
