Changeset 31815 for doc/nuxeo5-dev-quickstart-howto.txt

Timestamp:

05/07/08 10:33:54 (4 months ago)

Author:

sfermigier

Message:

Deprecate old doc.

Files:

• doc/nuxeo5-dev-quickstart-howto.txt (modified) (1 diff)

doc/nuxeo5-dev-quickstart-howto.txt

@@ -1 @@
-
-
-
+
+
-
-
-
-
-
-
-
+
-
-
-The goal of this document is to guide the interested newcomer on installing
-the necessary components to develop modules for the Nuxeo 5 Enterprise Platform.
-This setup assumes the use of Eclipse as target IDE and JBoss AS as target
-application server for deployments.
-
-This guide was written with Linux as a default operating system but remains
-appropriate for any other POSIX platform (such as Mac OS X). Minor changes
-might be required to adapt it on the MS Windows operating system.
-
-The reference (up-to-date) version of this document is located at:
-
-  http://svn.nuxeo.org/nuxeo/doc/nuxeo5-dev-quickstart-howto.txt
-
-.. sectnum::    :depth: 2
-.. contents::   :depth: 2
-
-Summary
-=======
-
-To *compile* Nuxeo 5, you will need to install:
-
-- Java 5 (latest JDK 1.5.0 from Sun) - not Java 6
-
-- Ant
-
-- Maven 2
-
-To *run* Nuxeo 5 EP, you will need:
-
-- JBoss AS 4.0.4.GA (**NOT JBoss AS 4.0.5.GA!**) with ejb3 profile
-
-To *work on Nuxeo 5 source*, an IDE is recommended:
-
-- Eclipse + SVN plugin (like Subclipse or Subversive)
-  + m2eclipse plugin (0.0.10 or later)
-
-or:
-
-- IDEA (after running "mvn idea:idea" from the command line)
-
-or:
-
-- Netbeans (not tested)
-
-Several other plugins are also recommended for greater efficiency, like
-the JBossIDE plugin for Eclipse, but not mandatory for building Nuxeo 5.
-
-
-Installing Java 5
-=================
-
-Nuxeo 5 uses the latest generation of Java technologies and thus requires a
-Java 5 VM such as the reference implementation by Sun.
-
-IMPORTANT WARNING: Nuxeo 5 doesn't currently compile under Java 6 (the 1.6.0 JDK from Sun). Even if it did, it is not clear that JBoss, the application server we are targeting, works under Java 6.
-
-
-Using package management systems
---------------------------------
-
-Some linux distributions now include Java 5 in their official repositories.
-
-For instance with Ubuntu (Edgy and later):
-
- - enable multiverse (2 lines to uncomment) in your /etc/apt/sources.list
- - update your package indexes::
-
-    $ sudo apt-get update
-
- - install the full java5 stack (probably not all is necessary)::
-
-    $ sudo apt-get install "sun-java5-*"
-
- - ensure Java 5 is now the default JVM on your system (instead of gcj and
-   friends by default)::
-
-   $ sudo update-alternatives --set java /usr/lib/jvm/java-1.5.0-sun/jre/bin/java
-
-(TODO: add similar instructions for Fedora Core and Debian)
-
-
-Manual installation
--------------------
-
-You can also manually install Java by following the instructions of this page:
-
-  http://www.java.com/en/download/linux_manual.jsp
-
-
-Setting up JAVA_HOME
---------------------
-
-In your .bashrc (or .zshrc, ...) add something like::
-
-  export JAVA_HOME=/usr/lib/jvm/java-1.5.0-sun
-
-This will be required by tools such as Maven (see later).
-
-
-Installing JBoss AS
-===================
-
-Nuxeo EP default target is the JBoss_ application server with EJB3 support
-enabled. To enable the EJB3 support, you should install JBoss with the
-latest version of the `Jems installer`_::
-
-  $ sudo java -jar jems-installer-1.2.0.BETA2.jar
-
-Note: Nuxeo5 does not work yet with jems-installer-1.2.0.BETA3.jar / JBoss AS 4.0.5
-
-While executing  the wizard you must select ejb3 install. You can leave all other
-parameters to their default values.
-
-If you get PermGenSpace errors when running the application:
-
-- Linux::
-
-    Edit `/opt/jboss/bin/run.conf` and add the following line at the end of
-    the file::
-
-       JAVA_OPTS="$JAVA_OPTS -XX:MaxPermSize=128m"
-
-    Restart JBoss.
-
-- Windows::
-
-    Edit '$JBOSS/bin/run.bat' and add the following line at the end of
-    the file::
-
-        set JAVA_OPTS=%JAVA_OPTS% -XX:MaxPermSize=128m
-
-    Restart JBoss.
-
-
-The default Nuxeo5 build setup expects to find JBoss in
-`/opt/jboss`. If you choose to install it elsewhere it is recommended
-to symlink `/opt/jboss` to your jboss installation directory.
-
-.. _JBoss: http://www.jboss.org
-.. _`Jems installer`: http://sourceforge.net/project/showfiles.php?group_id=22866&package_id=193295
-
-
-Installing a subversion client
-==============================
-
-
-Generic subversion clients
---------------------------
-
-The Nuxeo 5 source repository is a subversion_ repository thus you
-will need a subversion client to access the source code. Most linux
-distributions provide the ``svn`` command line tool. To install it under
-Ubuntu / Debian::
-
-  $ sudo apt-get install subversion
-
-Under Fedora Core this should become::
-
-  $ yum subversion
-
-You can then download the Nuxeo Enterprise Platform complete bundle with the following command::
-
-  $ svn checkout http://svn.nuxeo.org/nuxeo/nuxeo-ep/trunk nuxeo-ep
-
-You can now check the contents:
-
-  $ ls nuxeo-ep
-
-The official svnbook_ is a very good reference for both beginners and advanced
-subversion users.
-
-You can also browse the repository with any web browser using the trac
-interface:
-
-  http://svn.nuxeo.org/trac/nuxeo
-
-Under windows the recommended client is TortoiseSVN_.
-
-.. _subversion: http://en.wikipedia.org/wiki/Subversion
-.. _TortoiseSVN: http://tortoisesvn.tigris.org/
-.. _svnbook: http://svnbook.red-bean.com/
-
-
-Installing and using Apache Maven
-=================================
-
-What is Maven?
---------------
-
-Quoting the `Wikipedia entry for Maven`_:
-
-  Maven is a software tool for Java programming language project
-  management and automated software build. It is similar in functionality
-  to the Apache Ant tool, but has a simpler build configuration model,
-  based on an XML format. Maven is hosted by the Apache Software
-  Foundation, where it was formerly part of the Jakarta Project.
-
-  Maven uses a construct known as a Project Object Model (POM) to describe
-  the software project being built, its dependencies on other external
-  modules and components, and the build order. It comes with pre-defined
-  targets for performing certain well defined tasks such as compilation
-  of code and its packaging.
-
-  A key feature of Maven is that it is network-ready. The core engine can
-  dynamically download plugins from a repository, the same repository
-  that provides access to many versions of different Open Source Java
-  projects, from Apache and other organisations and developers. This
-  repository and its reorganized successor the Maven 2 repository are the
-  de facto distribution mechanism for Java applications. Maven provides
-  built in support not just for retrieving files from this repository,
-  but to upload artifacts at the end of the build. A local cache of
-  downloaded artifacts acts as the primary means of synchronizing the
-  output of projects on a local system.
-
-.. _`Wikipedia entry for Maven`: http://en.wikipedia.org/wiki/Apache_Maven
-
-
-Nuxeo currently uses maven to manage *build dependencies* both inside eclipse
-using the m2eclipse plugin (see later) and to build and deploy with ant.
-
-In the future maven will be used for the build and deployment step as well
-instead of ant.
-
-Nuxeo holds a maven repository here::
-
-   http://svn.nuxeo.org/maven/repo
-
-Installing the `felix` plugin
------------------------------
-
-This maven plugin is used to package modules as OSGi_ bundle::
-
-  $ svn co http://svn.apache.org/repos/asf/incubator/felix/trunk/tools/maven2/maven-osgi-plugin
-  $ cd maven-osgi-plugin
-  $ mvn clean install
-
-.. _OSGi: http://en.wikipedia.org/wiki/Osgi
-
-
-TODO: 2 lines to explain what a Maven repository is and how to setup the
-      jboss-* properties.
-
-
-Fetching the dependencies using the `mvn` command line utility
---------------------------------------------------------------
-
-You should then install Maven 2 on your dev box by downloading the latest
-tarball from http://maven.apache.org/download.html and then untar the archive
-in ``/opt`` for instance.
-
-Then add the ``bin/`` subdir in your PATH by adding something like the
-following in your ``.bashrc``::
-
-  export PATH=/opt/maven-2.0.4/bin:$PATH
-
-In a new shell you can then test::
-
-  $ mvn --version
-  Maven version: 2.0.4
-
-You can then use it on your Nuxeo EP checkout to download the dependency and launch
-the unit tests::
-
-  $ cd nuxeo-ep
-  $ mvn install
-
-
-Using a command-line Ant
-========================
-
-Installing
-----------
-
-Download the Ant package from http://ant.apache.org
-Untar it for example in /opt and have the executable (bin/ant)
-accessible in your PATH.
-
-Deploying
----------
-
-From the top of your nuxeo-ep checkout, you must first do a successful
-maven build (although it's recommended that you don't skip the tests)::
-
-  $ cd nuxeo-ep
-  $ mvn -Dmaven.test.skip=true install
-  $ ant clean
-
-The clean step is required to remove spurious files lef
-
-Then you can ask ant to do the deployment::
-
-  $ ant deploy
-
-You must have write permissions on the default server directory
-(/opt/jboss/server/default)
-
-If ant crashes or stops and doesn't answer ^C anymore, you may need to
-define the following environment variable::
-
-  $ export ANT_OPTS="-XX:MaxPermSize=128m"
-
-Once deployed you should be able to run nuxeo with::
-
-  $ /opt/jboss/bin/run.sh
-
-Or ``run.bat`` under windows.
-
-Then test the application by pointing your browser to:
-
-  http://localhost:8080/nuxeo
-
-And use Administrator / Administrator to log in.
-
-
-Running the tests
------------------
-
-In the nuxeo-ep folder::
-
-  $ mvn test
-
-Note that tests will take some time to complete (5 minutes on a recent laptop),
-since there are currently 3000 tests and some of them are a bit slow.
-
-You can also install it to be able to run specifically on one module::
-
-  $ mvn install
-  $ cd org.nuxeo.ecm.core
-  $ mvn test
-
-Since you are now running only a subset of all the tests, it will take less
-time to complete.
-
-
-Installing Eclipse
-==================
-
-Eclipse is both used as an IDE and a set of base components to build Rich
-Clients (Eclipse RCP).
-
-Some Linux distributions also include Eclipse but the Ubuntu packages
-I installed tended to be too much gcj oriented thus chose to download
-the tarball from eclipse.org:
-
-  http://www.eclipse.org/downloads/
-
-Then untar the archive in /opt for instance and then add a starter script such
-as the following somewhere in your PATH (eg. /usr/local/bin or ~/bin)::
-
-  #!/bin/bash
-
-  CMDLINEARGS=""
-  VMARGS="-Djava.net.preferIPv4Stack=true -Xms256m -Xmx1024m -XX:MaxPermSize=128m"
-  INSTALL="/opt/eclipse"
-  STARTUP="/opt/eclipse/startup.jar"
-
-  exec ${INSTALL}/eclipse \
-    -install "${INSTALL}" \
-    -startup "${STARTUP}" \
-    ${CMDLINEARGS} \
-    -vmargs ${VMARGS}
-
-Note on the vmargs:
-
-- the " -Xms256m -Xmx1024m" options are used to set the memory usage you allow
-  for the JVM used by eclipse (please adjust depending on your hardware)
-
-- the "-XX:MaxPermSize=128m" option is Sun specific is used to workaround a
-  `probable memory leak in the Sun JVM`_ (IBM/Jrockit should not be affected
-  by that bug and should not need that option)
-
-- the -Djava.net.preferIPv4Stack=true is useful, and sometimes mandatory, under linux to make jgroups work (useful for the cache system)
-
-.. _`probable memory leak in the Sun JVM`: http://eclipsezone.com/eclipse/forums/t77021.html
-
-Then open a shell and try::
-
-  $ eclipse
-
-The included tutorials are a good to familiarize your self with eclipse look and
-feel.
-
-The default build setup of Nuxeo 5 assumes that eclipse is installed in
-`/opt/eclipse`. If this is not the case, add a symlink there pointing to your
-installation or you will be required to update all the default build configuration
-files.
-
-
-Eclipse setup
-=============
-
-You can find useful tips and tools to better setup you eclipse environment in
-the following folder from the subversion repository::
-
-  $ svn co http://svn.nuxeo.org/nuxeo/tools/eclipse-config
-
-You should especially look at the following.
-
-
-Subversive plugin
------------------
-
-Subversive_ is an eclipse plugin to manage source code with subversion directly
-from the eclipse IDE.
-
-To install it, add a new remote site for Subversive with the software
-update manager using the following parameters::
-
-  Name: Subversive
-  URL: http://www.polarion.org/projects/subversive/download/1.1/update-site/
-
-This requires a write permission on /opt/eclipse/plugins.
-
-If you have never used the software manager before please follow these
-detailed instructions:
-
-  http://www.polarion.org/projects/subversive/download/Installation_Instructions.pdf
-
-Another subversion plugin named Subclipse_ is also available, although Nuxeo 5
-developers tend to recommend subversive instead::
-
-  Name: Subclipse
-  URL: http://subclipse.tigris.org/update_1.2.x
-
-.. _Subversive: http://www.polarion.org/index.php?page=overview&project=subversive
-.. _Subclipse: http://subclipse.tigris.org/
-
-
-Installing the Maven2 eclipse plugin
-------------------------------------
-
-As previously, use the Update Manager::
-
-  Name: m2eclipse
-  URL: http://m2eclipse.codehaus.org/update/
-
-You will need the most recent version of m2eclipse (0.0.10 at the time of
-writing this doc).
-
-You will now be able to run "mvn install" from inside eclipse by using the
-right click / "Run as" menu.
-
-
-Setup your Maven2 preferences within Eclipse
---------------------------------------------
-
-In Window > Preferences, select the Maven2 tab and set the repository to the
-one in your personal home folder (e.g. $HOME/.m2/repository). You can select
-all the options, and let the checksum policy to "warning". Then click on
-"reindex local repository" and apply changes.
-
-
-Install the AnyEdit Eclipse plugin
-----------------------------------
-
-AnyEdit_ is used to replace tabs with spaces and to remove trailing whitespaces.
-Feed the Update Manager with the following url::
-
-  Name: Andrei Loskutov
-  URL: http://andrei.gmxhome.de/eclipse/
-
-On the same site you will also find the JDepend4Eclipse plugin that is also
-worth installing to automate dependency analysis between packages.
-
-Note: apparently AnyEdit_ conflicts with the graphical process editor (JBPM)
-of the JBossIDE_ plugin. You might want to disable the AnyEdit while working
-on process definitions.
-
-.. _AnyEdit: http://andrei.gmxhome.de/anyedit/
-
-
-Install the JBossIDE_ eclipse plugin
-------------------------------------
-
-This is a plugin to help build applications running on the JBoss_ application
-server. Quoting from the site, JBossIDE_ features:
-
-   - EJB 3.0 Project Wizard
-   - Hibernate Tools
-   - Aspect Oriented Programming (AOP) Tools
-   - JBoss jBPM Graphical Process Designer
-   - Wizards to ease and simplify J2EE development
-   - Integrated debugging, monitoring, and lifecycle control of JBoss servers
-   - JSP, HTML, XML, CSS, and Javascript editors with syntax highlighting
-   - Easy configuration and deployment of package archives
-
-Note that JBossIDE  2.x is *not* required to work with Nuxeo 5.
-
-As usual, here are the references for the Update Manager::
-
-  Name: EMF Update Manager Site
-  URL: http://download.eclipse.org/modeling/emf/updates/
-
-NB :  This url seems to be dead :http://download.eclipse.org/tools/emf/updates/site.xml
-
-
-  Name: JBossIDE
-  URL: http://download.jboss.org/jbosside/updates/development
-
-The second site has dependencies on the first one: use the "Select required"
-to compute the dependencies automatically when selecting JBossIDE.
-
-.. _JBossIDE: http://labs.jboss.com/portal/jbosside/
-
-
-Eclipse configuration
----------------------
-
-Import the file ``nuxeo_codetemplates.xml`` into Eclipse::
-
-  In menu: Window > Preferences
-  Go to Java > Code Style > Code Templates
-  Click on import  and select the ``nuxeo_codetemplates.xml`` file
-
-Import the file ``nuxeo_formatter.xml`` into Eclipse::
-
-  In menu: Window > Preferences
-  Go to Java > Code Style > Formatter
-  Click on import  and select the ``nuxeo_formatter.xml`` file
-
-Set the preferences so that other files use spaces (not tabs), and set
-indenting to 2 spaces instead of 4 for XML-like files (XML files but also
-build files for instance)::
-
-  In menu: Window > Preferences
-  Go to General > Editors > AnyEdit Tools
-  Select all useful options (Remove trailing whitespaces, convert tabs to
-  spaces,... in "Auto-Convert" and "Misc. options" tabs)
-  Go to Ant > Editor > Formatter
-  Indent with size 2 and use spaces (no tabs).
-  Go to Web and XML
-  Go through sub directories (CSS files, HTML files, XML files, ...) and
-  select the source related preferences (CSS Source, HTML Source, XML
-  Source,...)
-  Repeat steps to set indenting using 2 spaces.
-
-When these settings are set, files can be reformatted easily in Eclipse: in
-menu, go to Source and select Format.
-
-Beware when formatting XHTML files, formatting is not always very legible.
-
-
-Optional Eclipse Plugins
-------------------------
-
-Check the "Improving code with Eclipse plugins" article on DeveloperWorks:
-
-  http://www-128.ibm.com/developerworks/java/library/j-ap01117/
-
-For a tutorial on 5 useful plugins related to code quality (coding standards,
-code duplication, code coverage, dependency analysis and complexity monitoring).
-
-These plugins are useful to keep up with the high standard of quality of the
-Nuxeo codebase.
-
-
-Load / checkout the org.nuxeo.* projects into eclipse
-=====================================================
-
-First create a new workspace make it point to the ``nuxeo-ep`` folder on you
-file system where you checked out the nuxeo source code::
-
-  File > Switch workspace > Other...
-
-Then register the nuxeo svn repository with subversive by going to the SVN
-repository perspective::
-
-  Help > Open perspective > Other... > SVN repository exploring
-
-The register the nuxeo repository with the following URL:
-
-  https://svn.nuxeo.org/nuxeo
-
-Then go back to the Java perspective and import the projects you have previously
-checked out as eclipse projects::
-
-  File > Import > General > Existing Projects Into Workspace
-
-This method is useful if you do not want to manage SVN through Eclipse,
-would like to have a checkout of the bundle, and would like to run tests
-using Maven within it (see below).
-
-Subversive should automatically reconnect all the projects to the SVN.
-
-Then it is recommended to::
-
-  Project > Clean ... > Clean on all projects
-
-
-Deploying from eclipse
-======================
-
-Once all the org.nuxeo.* projects build correctly in eclipse, you can deploy them on
-your JBoss instance directly from the IDE.
-
-In eclipse, add the ant view::
-
-  Window > Show View > Ant
-
-Then drag and drop the ``build.xml`` of the ``org.nuxeo.ecm.webapp`` to the ant view
-and then trigger the following target named ``deploy-ecm-all``.
-
-(Re)-start JBoss::
-
-  /opt/jboss/bin/run.sh
-
-If all went well, you should be able to access the application at:
-
-  http://localhost:8080/nuxeo
-
-Login with user name: Administrator (password: Administrator)
-
-
-Remote debugging in eclipse
-===========================
-
-Use case: suppose you just deployed Nuxeo 5 on your JBoss server and run into
-a new crash or any unexpected behavior. Instead of stopping the server and
-rerunning inside eclipse to reproduce the bug in the debugger, you can setup
-a new remote debugging profile for eclipse.
-
-- Linux::
-
-    First edit `/opt/jboss/bin/run.conf` and add the following line at the
-    end of the file::
-
-       JAVA_OPTS="$JAVA_OPTS -Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n"
-
-    Restart JBoss.
-
-- Windows::
-
-    Edit '$JBOSS/bin/run.bat' and modify the line:
-
-        rem set JAVA_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=y %JAVA_OPTS%
-
-    by erasing the remark ('rem'), and disabling the suspend ('suspend=n').
-
-    You should have::
-
-        set JAVA_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n %JAVA_OPTS%
-
-    Restart JBoss.
-
-Then from eclipse create a new debugger profile in menu: `Run > Debug ...`
-create a new `Remote Java Application` profile and set the source to the filesystem
-directory that host your complete eclipse workspace  and set the port to `8787`.
-
-Then edit the offending source code file and set breakpoints and run your
-new remote debug profile. From your web browser, refresh the page that was
-crashing and look back into eclipse: the debug perspective should open
-automatically at your fist breakpoint.
-
-
-
-
-Getting to understand the Nuxeo 5 architecture
-==============================================
-
-The ``/doc/`` folder as some interesting pieces of architectural overview such
-as following document:
-
-  https://svn.nuxeo.org/nuxeo/doc/Nuxeo-EP-5-Technical-Overview-1.0.odt
-
-Some important modules such as NXCore also have their own ``doc/`` subfolder:
-
-  https://svn.nuxeo.org/nuxeo/nuxeo-ep/trunk/org.nuxeo.ecm.core.repository/doc
-
-The wiki gathers pointers to the main tutorials and documentation:
-
-  http://svn.nuxeo.org/trac/nuxeo
-
-You can also browse the API with javadoc on the maven site.
-
-  http://maven.nuxeo.org/apidocs/
-