Difference between revisions of "Developer Guide"

From OpenKM Documentation
Jump to: navigation, search
 
(71 intermediate revisions by 3 users not shown)
Line 1: Line 1:
{{TOCright}} __TOC__
+
__NOTOC__
 +
The developer environment can be set in any Operating System (Linux, Windows, etc.) since it is a multi-platform system, but Linux is recommended, because is what it is being used.
  
The developer environment can be set in any Operating System (Linux, Windows, etc…) since it is a multi-platform system, but Linux is recommended, because is what it is being used.
+
{{Advice|[http://sourceforge.net/projects/openkmportabledev We've released '''Portable OpenKM development environment''', we encourage windows users use it. At the present still we do not have one for linux users.]}}
  
You need to install Maven, eclipse IDE and some plugins.
+
{{Note|[http://youtu.be/3h4R8AoN_BI Youtube - How to install OpenKM developement guide video]}}
  
For OpenKM 4.0 and 5.0
+
You need to install Maven, eclipse IDE and some plugins. For OpenKM 4.0 and 5.0 you have these requirements:
 
* Maven at http://maven.apache.org/
 
* Maven at http://maven.apache.org/
* Eclipse galileo ( Eclipse IDE for Java EE Developers ) at http://www.eclipse.org/galileo/
+
* Eclipse Juno (Eclipse IDE for Java EE Developers) at http://eclipse.org/juno/
* Subversion eclipse plugin at http://subclipse.tigris.org/update_1.6.x
+
* Subversion eclipse plugin at http://subclipse.tigris.org
* Maven to eclipse plugin at http://m2eclipse.sonatype.org/update
+
* Maven to eclipse plugin at http://m2eclipse.sonatype.org
* Java JDK 1.6  at http://java.sun.com/javase/downloads/index.jsp
+
* Java JDK 1.6  at http://www.oracle.com/technetwork/java/javase/downloads/index.html
  
== Configuring maven ==
+
{{Note|Starting from Eclipse Galileo you have a Marketplace accessible from Help > Eclipse Marketplace... Here you can search for "maven" to install the "Maven Integration for Eclipse" and "Maven Integration for Eclipse (Extras)" solutions. Also you can search for "subversion" to find the "Subclipse" plugin. See [http://www.imixs.org/roller/ralphsjavablog/entry/eclipse_indigo_maven_and_svn Eclipse Indigo - Maven and Svn].}}
Refer to maven installation at http://maven.apache.org/download.html#Installation
 
  
Really we'll use maven in operating system console only for some special operations like installing external libraries.  
+
{{Advice|The easier way to get an Eclipse installation with the required plugins is using [[JBoss Developer Studio]].}}
  
In GNU Linux Ubuntu for example you could be good adding it in ''$HOME/.bashrc''
+
Once all them are installed, you can download OpenKM and build it.
  
export PATH=$PATH:/home/jllort/software/apache-maven-2.2.1/bin
+
* [[Configure Java in Eclipse]]
 +
* [[Configure Tomcat server in Eclipse]]
 +
* [[Maven installation]]
 +
* [[Checkout source from Subversion]]
 +
* [[Development tips]]
 +
* [[Debug with Tomcat]]
 +
* [[Debugging remote Tomcat server]]
 +
* [[Debugging with GWT]]
 +
* [[Profiling OpenKM]]
 +
* [http://doxygen.openkm.com/ Doxygen OpenKM 6.2.x] ( OpenKM packages & classes & files documentation )
 +
* Doxygen OpenKM 5.1.x ( Deprecated, not available )
 +
* Doxygen OpenKM 5.0.x ( Deprecated, not available )
  
== Configuring java to eclipse ==
+
'''Note''': You can configure Eclipse to integrate with MantisBT. Read [http://sourceforge.net/apps/mediawiki/mylyn-mantis/index.php?title=Main_Page Mylyn-Mantis Repository Connector] for more info.
Go to '''Window''' / '''Preferences''' / '''Java''' / '''Installed JRE'''. You must have JDK 1.6 defined here.
 
  
[[File:Okm_dev_guide_004.jpeg‎|594px]]
+
== Eclipse Development Quick Install Guide ==
 +
This quick install is valid for Eclipse Indigo.
  
[[File:Okm_dev_guide_005.jpeg|481px]]
+
# Download '''Eclipse IDE for Java EE Developers''' from http://www.eclipse.org/downloads/.
 +
# Go to Help > Eclipse Marketplace and install these plugins:
 +
## [http://marketplace.eclipse.org/content/maven-integration-eclipse Maven Integration for Eclipse]
 +
## [http://marketplace.eclipse.org/content/subclipse Subclipse]
  
== Checkout OpenKM from svn ==
+
'''Alternative: Add repository'''
Go to '''File''' / '''New''' / '''Other''' and select '''Maven''' / '''Checkout Maven Projects from SCM'''
+
* Subclipse 1.6.x Update Site -> http://subclipse.tigris.org/update_1.6.x
 +
* Maven Integration for Eclipse - http://m2eclipse.sonatype.org/sites/m2e/
 +
* Maven Integration for Eclipse Extras - http://m2eclipse.sonatype.org/sites/m2e-extras/
  
[[File:Okm_dev_guide_001.jpeg‎|459px]]
+
== Know problems ==
 
+
When you build application on windows you can get the error '''create process error 206 the filename or extension is too long''' this is caused to a Windows OS limitation. To solve it is needed move '''.m2''' repository to '''c:\''' then go to Eclipse > Windows/Preferences/Maven/User Settings -> Create your own setting.xml with this content:
Select the '''svn''' type and typewrite the url https://openkm.svn.sourceforge.net/svnroot/openkm/branches/4.0/openkm to refer version 4.0.
 
 
 
{|
 
|[[File:Okm_dev_guide_002.jpeg‎|459px]]
 
|[[File:Okm_dev_guide_003.jpeg‎|459px]]
 
|}
 
 
 
Be patient, first time you downloading OpenKM from svn, you're downloading all libraries to your maven repository. It could need some hours depending your Internet connection.
 
 
 
After OpenKM it'll be downloaded, automatically it'll be compiled
 
 
 
== Installing external libraries to maven repository ==
 
Open an operating system console.
 
Go to your OpenKM project path in your file system.
 
Come into ext-libs and execute install.sh ( Windows users simply open this file with text editor and execute the command )
 
 
 
== Execute packaging ==
 
In Eclipe select openkm root folder. Open contextual menu and select '''Run As''' / '''Maven Package'''
 
OpenKM.War it'll be appears created under target folder
 
 
 
[[File:Okm_dev_guide_006.jpeg‎|192px]]
 
 
 
== Configuring JBoss server ==
 
Go to servers tab Using contextual menus select '''Add''' / '''server'''. Select JBoss server
 
 
 
{|
 
|[[File:Okm_dev_guide_007.jpeg‎|459px]]
 
|[[File:Okm_dev_guide_008.jpeg‎|459px]]
 
|-
 
|[[File:Okm_dev_guide_009.jpeg‎|459px]]
 
|[[File:Okm_dev_guide_010.jpeg‎|459px]]
 
|}
 
 
 
== Recomendations ==
 
We recommend downloading JBoss+OpenKM from SourceForge, remove OpenKM.war and develop with this JBoss server configuration. For better development we recommend not deploying OpenKM.war file it's better setting in $JBOSS_HOME/server/default/deploy some alias to target/OpenKM folder
 
 
 
[[File:Okm_dev_guide_011.jpeg‎|441px]]
 
 
 
In case you're making strong changes in OpenKM UI ( GWT ) we recommend disabling pom compile directive
 
  
 
<source lang="xml">
 
<source lang="xml">
<plugin>
+
<settings>
    <groupId>org.codehaus.mojo</groupId>
+
  <localRepository>c:/.m2/repository</localRepository>
        <artifactId>gwt-maven-plugin</artifactId>
+
</settings>
        <version>1.1</version>
 
        <configuration>
 
            <runTarget>es.git.openkm.frontend.Main/index.html</runTarget>
 
        </configuration>
 
        <executions>
 
          <execution>
 
            <goals>
 
              <!-- <goal>compile</goal> -->
 
              <!-- <goal>generateAsync</goal>  -->
 
              <goal>test</goal>
 
            </goals>
 
          </execution>
 
        </executions>
 
    </plugin>
 
 
</source>
 
</source>
  
You might be interested in running frontend and backend GWT packaging from eclipse. Go to run configurations and add in maven build
+
== Deprecated ==
 
+
=== OpenKM version 5.x and older ===
[[File:Okm_dev_guide_012.jpeg‎|800px]]
+
* [[Configure JBoss server in Eclipse]]
 
+
* [[Debugging remote JBoss server]]
[[File:Okm_dev_guide_013.jpeg‎|800px]]
+
* [[Browsing embeded database]]
 +
* [[Debugging OpenKM with JBoss]]
  
To achieve a faster compile we use to development Firefox, uncommenting gecko line on file Main.gwt.xml GWT compilation only for gecko browser runs fine. Don't forget at finish to comment it and try application with IE or other browsers. Now are two files called Main.gwt.xml one for frontend and other to backend.
+
== Changelog ==
 
+
==== Changes between developer guide 5.0 to 6.0 ====
<source lang="xml">
+
* GWT 2.4.0
<!-- Compile for Firefox only -->
+
* OpenKM now is executed under tomcat
<set-property name="user.agent" value="gecko"/>
+
* Changed to Eclipse Juno
</source>
 
  
 
==== Changes between developer guide 4.0 to 5.0 ====
 
==== Changes between developer guide 4.0 to 5.0 ====
* GWT 1.7.1
+
* Development tips changes ( how to enable OpenKM extensions in compilation and disable automatic GWT compilation )
 +
* GWT 2.0.4
 +
* Java package has been refactoring to "com.openkm" all references to older package in configuration files has been changed
  
 
==== Changes between developer guide 2.0 to 4.0 ====
 
==== Changes between developer guide 2.0 to 4.0 ====
Line 114: Line 79:
  
 
==== Changes between developer guide 1.2 to 2.0 ====
 
==== Changes between developer guide 1.2 to 2.0 ====
 
 
* Changed IDE to Eclipse Europa / JBoss tools, before was JBoss IDE.
 
* Changed IDE to Eclipse Europa / JBoss tools, before was JBoss IDE.
 
* GWT 1.5.3 is needed to compile, before was version 1.4.6
 
* GWT 1.5.3 is needed to compile, before was version 1.4.6
Line 123: Line 87:
  
 
==== Changes between developer guide 1.0 and 1.1 to 1.2 ====
 
==== Changes between developer guide 1.0 and 1.1 to 1.2 ====
 
 
* GWT 1.4.6 is needed to compile, before was version 1.3.3.
 
* GWT 1.4.6 is needed to compile, before was version 1.3.3.
 
* Changes on GWT shell configuration, now not uses GWTDS variable ( code deleted ).
 
* Changes on GWT shell configuration, now not uses GWTDS variable ( code deleted ).
Line 129: Line 92:
 
* Added gecko to Main.gwt.xml to fast compiling only gecko when is uncommented.
 
* Added gecko to Main.gwt.xml to fast compiling only gecko when is uncommented.
  
==== Developers support on environment changes ====
+
[[Category: Developer Guide]]
 
 
If you are a developer or simply you want to be informed when some changes are made and affect to developer environment, [http://www.openkm.com/Contact/ email us] and we'll tell you, because developer guide only it'll be remixed when a new version it'll be released at last.
 
 
 
We think development environment now is fine, and we doubt change it on new version. Although it, especially when we make repository upgrades is needed on development to recreate repository several times on a week, this could be unpleasant for some developer if no are informed about it, because one or two weeks could be especially difficult to get a good SVN compiling code without problems. Normally when we are upgrading repository, the developers that are making UI changes must not check-outs SVN code for some time
 
 
 
[[Category: OpenKM 4.0]]
 
[[Category: OpenKM 5.0]]
 

Latest revision as of 18:11, 27 February 2015

The developer environment can be set in any Operating System (Linux, Windows, etc.) since it is a multi-platform system, but Linux is recommended, because is what it is being used.


Nota idea.png We've released Portable OpenKM development environment, we encourage windows users use it. At the present still we do not have one for linux users.


Nota clasica.png Youtube - How to install OpenKM developement guide video

You need to install Maven, eclipse IDE and some plugins. For OpenKM 4.0 and 5.0 you have these requirements:


Nota clasica.png Starting from Eclipse Galileo you have a Marketplace accessible from Help > Eclipse Marketplace... Here you can search for "maven" to install the "Maven Integration for Eclipse" and "Maven Integration for Eclipse (Extras)" solutions. Also you can search for "subversion" to find the "Subclipse" plugin. See Eclipse Indigo - Maven and Svn.


Nota idea.png The easier way to get an Eclipse installation with the required plugins is using JBoss Developer Studio.

Once all them are installed, you can download OpenKM and build it.

Note: You can configure Eclipse to integrate with MantisBT. Read Mylyn-Mantis Repository Connector for more info.

Eclipse Development Quick Install Guide

This quick install is valid for Eclipse Indigo.

  1. Download Eclipse IDE for Java EE Developers from http://www.eclipse.org/downloads/.
  2. Go to Help > Eclipse Marketplace and install these plugins:
    1. Maven Integration for Eclipse
    2. Subclipse

Alternative: Add repository

Know problems

When you build application on windows you can get the error create process error 206 the filename or extension is too long this is caused to a Windows OS limitation. To solve it is needed move .m2 repository to c:\ then go to Eclipse > Windows/Preferences/Maven/User Settings -> Create your own setting.xml with this content:

<settings>
  <localRepository>c:/.m2/repository</localRepository>
</settings>

Deprecated

OpenKM version 5.x and older

Changelog

Changes between developer guide 5.0 to 6.0

  • GWT 2.4.0
  • OpenKM now is executed under tomcat
  • Changed to Eclipse Juno

Changes between developer guide 4.0 to 5.0

  • Development tips changes ( how to enable OpenKM extensions in compilation and disable automatic GWT compilation )
  • GWT 2.0.4
  • Java package has been refactoring to "com.openkm" all references to older package in configuration files has been changed

Changes between developer guide 2.0 to 4.0

  • Changed to Eclipse Galileo
  • Now we use maven in replacement of JBoss Tools

Changes between developer guide 1.2 to 2.0

  • Changed IDE to Eclipse Europa / JBoss tools, before was JBoss IDE.
  • GWT 1.5.3 is needed to compile, before was version 1.4.6
  • Changed packaging to new jboss tools packaging.
  • Changed GWT generating to temporary JBoss folder to project folders to developing.
  • Added new generateback.sh and generateback.bat to GWT admin.
  • Upgraded JBoss server to version 4.2.2.GA

Changes between developer guide 1.0 and 1.1 to 1.2

  • GWT 1.4.6 is needed to compile, before was version 1.3.3.
  • Changes on GWT shell configuration, now not uses GWTDS variable ( code deleted ).
  • Configured generate.sh to deploy to tmp JBoss with OpenKM.ear deployed to fast developing.
  • Added gecko to Main.gwt.xml to fast compiling only gecko when is uncommented.