Why are there so many error and omissions in the developer's documentation? Do outsiders ever actually compile Nuxeo?

[utopian]

I'm new to Nuxeo. I'm trying to understand the system, and in particular I'm trying to find out why I'm getting an SQL error when trying to create a workspace. I figured installing and running the source code would be the best place to start. I've come across many errors and gaps in the documentation. I'm wondering if compiling from source is really viable.

Firstly it strikes me as odd that the download process is done via Python, from the command line. From within Eclipse, we have Git, Maven, Ant, and whatever else is available in the Nuxeo plug-in for Eclipse. The choice of Python strikes me as odd. But anyway on to my specific observations...

Some commands work in UNIX but not Windows. This is for UNIX:

export MAVEN_OPTS="-Xmx1g -XX:MaxPermSize=128m"

This is for Windows:

set MAVEN_OPTS=-Xmx1g -XX:MaxPermSize=128m

This is just mean:

"The following assumes you know how to work with Maven and sources in your IDE (Eclipse is used below). In particular this means that you have already configured the IDE to work with Maven (M2_REPO set in Eclipse)."

I mean, OK, I don't know Maven. Even so, a little help here? All you need to say is "M2_REPO set in Eclipse via Windows | Preferences | Java > Build Path > Classpath Variables"

The documentation fails to mention that you need to install GNU DiffUtils. That clue is hidden in the fixeclipse.py script, which fails on Windows with an uninformative error if "diff" isn't available.

Given the large number of dependencies, it would be ideal if there was some type of "check setup" tool which confirmed that the correct tools are installed, and the correct version. By way of example, if you happen to be using a JRE instead of a JDK, Maven will take 45 minutes before reporting failure, when running "mvn -DskipTests install -Paddons"

On http://doc.nuxeo.com/display/CORG/Compiling+Nuxeo+from+sources, they say "See README file at root of nuxeo-distribution for a short description and common usage examples." There is no such README file.

On the same page, the instructions say "Ant is available at the top level: Ant targets have been defined to provide user-friendly commands..." The one example Ant command is 'distrib,' which is not present in nuxeo/build.xml.

The instructions say to import Nuxeo modules into Eclipse. The provided instructions say "File -> Import -> General -> Existing Projects into Workspace" What isn't stated is WHAT projects to import. I have no idea if I got this right, but I imported all the projects in nuxeo, nuxeo/nuxeo-common, nuxeo/nuxeo-core, etc, all the way to nuxeo/nuxeo-webengine. So I invoked the Eclipse import process 11 times in all. At that point I was still getting errors, so I imported nuxeo/addons/nuxeo-shell, as it was required by nuxeo-launcher. So "nuxeo-shell" doesn't seem like an addon, it seems required. Anyway now I have 236 projects in Eclipse. That doesn't feel right. But maybe it is. Who knows? The lack of screenshots leaves me with no idea if I'm offtrack.

I now have all the projects in Eclipse. But they are not connected to Git. So if I want to get an update, I can't do that.

With all these projects in Eclipse, I have no idea how to proceed. With the downloadable SDK, there are instructions (http://doc.nuxeo.com/display/IDEDOC). But with the source code (http://doc.nuxeo.com/display/CORG), I have no idea. I've got all the code, and when I run maven commands they seem to do stuff. But, in Eclipse, I can't even figure out how to start the server.

So, I know that is a lot of stuff. I guess my root questions are:

1. Once I've got all this source code, how do I start the server?
2. Do people outside the Nuxeo company actually compile the source code?

[bruce_Grant]

I can only speak for myself but I have compiled (successfully) the source code; although I haven't done a full build in a while. So it is possible. When I need to change a core component (if you use DAM in any serious way with big objects, multiple formats and colorspaces then you will find it unavoidable) I do not recompile the entire platform. In this case I...

• get the latest updated source using python (agreed this is a little odd),
• import the project of interest into Eclipse,
• use git (command line) to switch to the release or hotfix of interest,
• make the changes in Eclipse,
• make a local commit,
• use maven (command line) to recompile the affected project(s), and
• then deploy the updated JAR to the server.

Because there are so many different technologies and moving parts compiling from source is challenging - especially for those new to Nuxeo. It would be extremely useful if there were recorded webinars for activities like building a server from scratch.

[ben-Nabiy_Derus]

It would be extremely helpful to have that kind of documentation. I think many are intimidated by the complexity of a "machine" with many working parts. It would be good to have a section which is dedicated to technical walk-throughs etc. I know it is somewhat counterproductive to your support side of things, but in the end, the less calls you have to deal with on petty matters, the better.

[Julien_Carsique]

Hi,

Let's first answer your two last questions:

1. You don't need the source code to start the server: source code is for building the server.
2. Yes, they do but this is only useful for contributors (ie advanced Nuxeo core developers). Nuxeo is designed in order to never require to change the source code, only to extend or overwrite it.

Here are a few answers to your questions or remarks:

• First of all, you can see the documentation is huge and requires a continuous maintenance. Remarks and contributions are welcome.
• Solving your SQL error has to do with server administration, logs analysis, asking questions like you did on why-do-i-get-an-error-occured-when-creating-a-workspace... building the source code won't help.
• Of course, << compiling from source is really viable >> since we do it everyday and have and advanced continuous integration building the source code too.
• The README (have been renamed from .txt to .md), I've updated the doc, thank you.
• About Ant, the end of the sentence you pointed is << we don't cover all possibilities and Ant targets may be out of date >>. We recommend to use Maven. Ant scripts are kept for their aficionados and maintained by contribution only.
• I'm sorry you fall into so much headaches but the CORG part of the documentation is effectively focused on Linux and addressed to advanced (Nuxeo) developers. All your other remarks are out of purpose too. I could answer and explain in details to each one but there would be no point at doing it, it wouldn't help you.
• Starting the server in Eclipse (Nuxeo IDE) is done with "Nuxeo > Run/Debug" as explained in IDEDOC/Running your Projects on the Server.

Regards,

[utopian]

First, sorry for being so cranky. By way of context, if I can't get Nuxeo working, we are probably going with hosted SharePoint

[Alain_ESCAFFRE]

Hi Utopian,

First, I am glad you get interest on Nuxeo product and community and hope you will find what you need here. I also hope you'll get the habit of asking only one question per post, that's the way this "answers" tool should be used. I think it is interesting to mention here that for most (if not 100%) of any customization use case (whether from IDE or Studio) you don't need to compile Nuxeo sources. Nuxeo is fully extensible and customization is made in external bundles (the "plugins"). That's probably why the "checkout Nuxeo sources" path is not fully optimized.

Of course, checking out the sources is a recommended path if you want to accelerate your learning curve of the framework, since you will find in there many interesting examples (as your customization is made the same way the built-in bundles are made). But even then, you don't need to build the product, you just get them locally to be able to browse the sources comfortably.

The main case where you really want to build from the sources is if you want to test then contribute some bug-fixes via pull requests and we will be glad if you can do so !

[Alain_ESCAFFRE]

Sorry guys, I had missed all the answers before

[ben-Nabiy_Derus]

It was still nice to see your comment. It seems that many miss the fact that Nuxeo is fully extensible by way of plugins.