| Setting up an IDE for Development |
| |
|
In this document I will provide a brief overview on what is needed to compile
contineo by yourself. This document focuses on Windows, but the basic idea is
the same for Linux.
|
| |
| Java Setup |
| |
|
Since contineo is a Java web application, you also need Java installed to run
and compile contineo. Download the latest stable Java Development Kid (JDK) from
Sun and install it using the
provided installation routines. Also set the environment variable JAVA_HOME in
your system settings. This variable should point to where you installed the JDK,
so something like c:\programme\java\jdk1.5.0_11. And don't download the J2EE
version, this is not needed for our purpose.
|
| |
| General Folder Structure |
| |
|
There are various things we have to download and install. For example we have
the source code, the compiled code running in a Java web server (like Tomcat),
Eclipse, and the database directory. Therefore I suggest to create a folder
c:\contineo to store everything there. In the following section all explanations
are based on the assumption that you use this folder as a base.
|
| |
| Installing Tomcat |
| |
Contineo is executed in a web server providing Java support (a so called servlet
container). There are many products available, however I suggest to use Apache Tomcat, because it
is very easy to install. While writing this document the current stable version
is 5.5.X. So you should also download the latest stable ZIP distribution. Unpack
this ZIP file to c:\contineo\tomcat. In tomcat\conf\tomcat-users.xml add the
following line to also have admin access to Tomcat:
<user username="admin" password="admin" roles="manager"/>
Of course choose a better password! Now you can start Tomcat using the
tomcat/bin/startup.bat script. With a browser go to the URL
http://localhost:8080/. You should now see the Tomcat start page. Try the
"Status" and "Manager" page (you need the admin login added
above). Also check if the example apps are running.
|
| |
| Installing Eclipse |
| |
|
There are many Java IDEs available. So if you already have your preferred one
stick to it! If you don't have one, I suggest to try Eclipse. Make sure you have
at least version 3.1, because older versions do not fully support Java 1.5.
Download the SDK. You don't need the other packages. Extract the package to
c:\contineo\eclipse. On Eclipse's first startup you have to select a workspace
path. In this path general project settings are stored. It is not the folder
where the source is stored. So basically you are free to choose whatever you
want. If Eclipse is working, you can shutdown it for the moment. We will come
back to it later.
|
| |
| Getting the Source Code |
| |
|
Now we are getting to the interesting things. We want to get contineo's source
code. You can either download a source package from SourceForge or you can
checkout the latest source code from SVN.
|
| |
|
In case you want to get the latest source from SVN, it is getting a little bit
more complicated. First of all you need a SVN client. I suggest Tortoise, which is
shipped together with the necessary command line tools. Please see Tortoise's
homepage for installation instructions. There is a detailed
documentation available on Sourceforge to set up the SVN client. Please
follow the instructions there.
|
| |
|
If you set up the SVN stuff correctly, you should be able to download
contineo's source code directly from the source repository. The checkout might
take some time.
|
| |
|
Now you have the source code, maybe in the folder c:\contineo\contineo\contineo.
Take some minutes to get familiar with the folder structure before going on.
|
| |
| Compiling the Source Code using Maven and Eclipse |
| |
|
Contineo uses the configuration management system Maven. Before you can easily
build contineo, you have to install Maven (version 2 or later). Please see
Maven's homepage for installation instructions.
|
| |
|
Before you can compile the source code, you have to first install some libaries
in your local maven repository. The necessary libs are available in contineo's
SVN repository and a batch file is provided to make the installation as easy as
possible. Go to the directory "contineo/trunk/contineo/etc" and start
the batch file. In case you are using Microsoft Windows use the file with the
ending ".bat", in case you are using Linux use the file with the
ending ".sh".
|
| |
Now look for the folder containing the "pom.xml" file. You should be
able to find the file in the following directory:
"contineo/trunk/contineo". Open a command line (shell) and issue the
following command:
mvn compile
Maven will first download all libraries needed to compile contineo. Afterwards
it will compile contineo. Depending on your Internet connection, this may take
some minutes. It is not necessary to download the libraries each time you want
to compile the code. Instead, use the "-o". This tells Maven to not
download the libraries and work offline instead.
|
| |
Now it is time to create a package, which can be deployed on your server. This
is also very easy to do. Just issue the following Maven command:
mvn -o package
First, it will check that all files are compiled. Afterwards, it will execute a
set of automated test cases. Those test cases ensure that your code changes do
not break any existing functionality. Please make sure that you also write test
cases for any new functionality! If all test cases passed successfully a package
will be created. This package can be found in the "target/"
directory. The war file is ready to be deployed on your server. You can follow
contineo's general installation instructions to do so.
|
| |
Executing the test cases each time can be time consuming. You can also skip the
test run by adding the "-Dmaven.test.skip=true" switch to your Maven
command. So far we already compiled the source code and also created a package.
Still, not everybody might be in favour to edit the source files using a text editor. Therefore it is
possible to generate the necessary project files for Eclipse with the following
Maven command:
mvn -o eclipse:eclipse
You can open the project very easily in Eclipse. First, start Eclipse and
select "Import" from the "File" menu. In the wizard, select
"Existing Projects into Workspace" from the "General" import
category. Set the folder containing the "pom.xml" file as the root
folder and press "Finish". It will now import the project into Eclipse
and build it. This may take some time also depending what kind of plugins you
have installed in Eclipse (like XML validation). You can now change the code in
Eclipse and it will immediately compile your changes. Before you submit any
changes to SVN, make sure to run the Maven test cases. This can be not done
directly from Eclipse as far as I know.
|
| |
|
In the following section I will explain how to run contineo without having to
deploy it each time manually.
|
| |
| Run Contineo |
| |
It would be quite complicated to manually deploy contineo each time in Tomcat
after some code changes were done. It would be perfect if a code change would
just require restarting the server. It is possible to do this. You just have to
create a context in Tomcat pointing at the directory containing the classes
built by Eclipse. In order to do so, navigate to Tomcat's installation directory
and go into the sub-directory "conf/Catalina/localhost". Create a new
file called "contineo.xml" with the following content:
<Context
docBase="c:/contineo/svn/contineo/trunk/contineo/target/contineo-3.0beta1/">
</Context>
Of course you have to adjust the "docBase" value according to your
local installation. Now you can restart Tomcat and you should be able to load
contineo using the following URL: http://localhost:8080/contineo/. On the first
execution you have to go through the setup procedure as for every ordinary
contineo installation. See the section below for some more pointers. Each time
you change the code, you just have to restart Tomcat. Even if you are just
compiling inside of Eclipse, it will update the correct files in the target
directory so that you do not have to execute Maven again.
|
| |
| Installing Contineo |
| |
You have to install contineo by browsing to
http://localhost:8080/contineo/setup/. You can follow the install instructions. I suggest to use the
following settings:
- c:/contineo/data/log/THE_DIFFERENT_LOGFILES.log
- c:/contineo/data/docs/
- c:/contineo/data/index/
- c:/contineo/data/users/
- c:/contineo/data/backup/ (you do not have to enable backup,
but at least set a path)
- use the internal database management system (HSQLDB)
c:/contineo/data/db/ -> try later other DBMS and fix bugs you
encounter
- create an admin account
Check after each setup step, if the necessary files and directories are created.
|
| |
| Debugging Contineo |
| |
|
It is possible to debug contineo running on Tomcat. From a debugging perspective
it looks like if you debug an ordinary application from within Eclipse. To be
able to do so, you need to activate remote debugging in Tomcat and set up
Eclipse to connect to Tomcat for debugging.
|
| |
|
First configure Eclipse, because that is the more easier part. Select
"Debug..." from Eclipse's "Run" menu. In the list on the
left side click on "Remote Java Application" and select
"New" from the right-click menu. Just leave all settings as they are.
|
| |
Tomcat supports remote debugging, but it is not enabled by default. You have to
start Tomcat with the "jpda start" command line option. On Linux, I
changed the last line of the "startup.sh" file as follows:
exec "$PRGDIR"/"$EXECUTABLE" jpda start "$@"
On Windows I changed "startup.bat" file replacing one of the last
lines with the following one:
call "%EXECUTABLE%" jpda start %CMD_LINE_ARGS%
I also had to change the "catalina.bat" on Windows. I added the
following 2 lines after the header of the file:
set JPDA_TRANSPORT=dt_socket
set JPDA_ADDRESS=8000
Now, the only thing left to do is to start Tomcat and connect the Eclipse
debugger to the running Tomcat instance. After Tomcat was started, select again
the "Debug..." dialog and execute the debug entry you created before.
Eclipse now connects to Tomcat and Eclipse's debugger will be called as usual,
if you reach a break point. This is a very convenient way of working and it
speeds up development heavily.
|
| |
| Few more Hints |
| |
|
Now you should have a running contineo. If you change the code, make sure it
gets recompiled by Eclipse. Do not forget to restart Tomcat. If you are
debugging contineo using remote debugging, it might also be possible to run
changed code without having to restart Tomcat. However, this doesn't seem to
work in all cases, so test it by yourself!
|
| |
I suggest to create desktop shortcuts to the following things:
- URL Link to contineo's main page
(http://localhost:8080/contineo/)
- Eclipse
- Tomcat startup and shutdown scripts
- Source code directory
|
| |
|
There is a special mailing list with SVN commit messages. Each time
something is changed in the SVN repository, an email is send to this mailing
list. If you prefer RSS updates, make sure to add the RSS feed on the
following page to your RSS reader!
|
| |
|
That are the basic steps needed to compile and run contineo. Now start playing
around with the source code. We hope to see your contributions soon!
|
