[kune-commits] r1047 - trunk

Tue Feb 10 18:00:57 CET 2009

Author: vjrj
Date: 2009-02-10 18:00:56 +0100 (Tue, 10 Feb 2009)
New Revision: 1047

Modified:
   trunk/DEV-GUIDE
Log:
dev guide improved

Modified: trunk/DEV-GUIDE
===================================================================

--- trunk/DEV-GUIDE	2009-02-03 10:53:22 UTC (rev 1046)
+++ trunk/DEV-GUIDE	2009-02-10 17:00:56 UTC (rev 1047)
@@ -1,32 +1,143 @@
-=DEVELOPMENT GUIDE=
+=Kune developer's guide=
 
+''This is the trunk/DEV-GUIDE file (must have the same content as the [http://kune.ourproject.org/wiki/index.php?title=Kune_developer's_guide wiki page])''
+
+==Some other relevant docs for kune development==
+
+* trunk/img/kune-arch.png          # architecture diagram
+* trunk/INSTALL
+* trunk/TROUBLESHOOT
+* trunk/FAQ
+* trunk/HOWTO_ADD_A_NEW_TOOL
+
+If you are interested in the db schema:
+* trunk/img/kune-hibernate-diagram-oct-08.png
+but is more easy to look in the Java classes of package org.ourproject.kune.platf.server.domain.
+
+* [http://kune.ourproject.org/spip.php?article15 Video/presentation of kune]
+* trunk/kune-diagram-part1-0.1.png # old diagrams but a good brief
+* trunk/kune-diagram-part2-0.1.png 
+* trunk/kune-diagram-part3-0.1.png 
+
+==Languages and frameworks used in kune development==
+
+===Java===
+
+The 2/3 main parts of kune are developed in Java. The server code, and the desktop client code.
+
+===GWT===
+
+[ GWT] is used for the client workspace. For some dev 
+
+===Rails===
+
+GWT is used for the public more static front-end.
+
+===HTML/CSS/JavaScript===
+
+All the HTML/JavaScript code of the client workspace is generated from the Java code using GWT. We use some minimal html/css (see kune.css, doc.css, workspace.css, Kune.html) plus this generated js.
+
+All the workspace css are concatenated and compressed using csstidy (see script/css-compact-and-tidy.css if you want to know how).
+
+==Notable dependencies==
+
+For a more detailed list of dependences see trunk/pom.xml file.
+
+===Server side===
+
+====guice====
+
+[http://code.google.com/p/google-guice/ Guice] is used in server code for [http://en.wikipedia.org/wiki/Inversion_of_Control IoC]. As they describe «Put simply, Guice alleviates the need for factories and the use of new in your Java code. Think of Guice's @Inject as the new new.».
+
+As we cannot use guice in client code, we use our other project [http://suco.googlecode.com suco] that is inspired in guice.
+
+For use details see the [http://google-guice.googlecode.com/files/Guice%201.0%20User%27s%20Guide.pdf Guice User's Guide].
+
+====Apache OpenJPA====
+
+For persistence, we use [http://openjpa.apache.org/ OpenJPA]. See the [http://openjpa.apache.org/docs/openjpa-0.9.0-incubating/manual/manual.html openjpa manual] for dev info.
+
+====Warp persist====
+
+We use [http://www.wideplay.com/guicewebextensions2 warp-persist] and [http://www.wideplay.com/dynamicfinders dynamic finders]. That is Guice + Persistence.
+
+====lucene====
+
+For content indexing, we use lucene.
+
+===client side (GWT)===
+
+====Suco====
+
+[http://suco.googlecode.com suco] is our IoC library for GWT. For more documentation see [http://code.google.com/p/suco/w/list the suco wiki] or our HelloWorldModule class.
+
+====Emite====
+
+[http://emite.google.code emite] is our xmpp library a client. See [http://code.google.com/p/emite/w/list the wiki] for more documentation about emite.
+
+====gwt-ext====
+
+[http://gwt-ext.com/ gwt-ext] is used for our gwt UI. See the [http://www.gwt-ext.com/demo showcase demo] for sample codes.
+
+====gwt-ext-ux====
+
+We use some widgets from the [http://code.google.com/p/gwt-ext-ux/ gwt-ext-ux] project (mainly the File Uploader).
+
+====gwt-log====
+
+We use [http://gwt-log.googlecode.com/ gwt-log] as the log library for our GWT code. Also gwt-log is used in emite and suco. See [http://code.google.com/p/gwt-log/wiki/GettingStarted GettingStarted] for more details.
+
+===client side (Rails)===
+
+====jruby====
+
+====rack====
+
+==Some recomendations==
+
+===Designs patterns===
+
+* MVC: We use a lot the [http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller MVC pattern] in our GWT code. See our HelloWorldModule class for a simple sample. We used to auto generate some MVC classes with the script script/generateBasicUIElements.sh.
+
+* IoC: as we described before we use guice and suco for IoC. See HelloWorldModule class for a very simple sample of gwt module using suco.
+
+===Usability===
+
 ==Development Environment==
 
-Install kune (see INSTALL file).
+===Prerequisite: Install kune===
 
-Running (in the trunk directory)
+Install kune (see trunk/INSTALL file) and run kune for the first time.
 
+===Eclipse configuration===
+
+Running (in the trunk directory):
+
  mvn eclipse:eclipse 
 
 generates .project and download necessary code jars. Then you can import the project in eclipse (File > Import > Existing Projects into Workspace). 
 
 Also you have to set the variable M2_REPO (Eclipse Preferences > Java > Build Path > Classpath Variables > New) to the location of your local maven repo (in our case /home/ouruser/.m2/repository).
 
-GWT Hosted Mode:
+===GWT's Hosted Mode===
 
-We have a "Run configuration" (Run > Open Run Dialog) in eclipse with Project: "org.ourproject.kune" with Main class: "com.google.gwt.dev.GWTShell", with this program arguments (or similar): "-noserver -out gwt-out /kune/?locale=en&log_level=INFO -port 8080" and in the "Classpath User Entries":
-* gwt-dev-[linux|mac|windows].jar (Add External Jar and select it from your gwt installation directory)
+For start the hosted mode, you can both execute from command line:
+
+ mvn gwt:gwt
+
+Also, you can generate a hosted mode launch configuration in eclipse. We have a "Run configuration" (Run > Open Run Dialog) in eclipse with Project: "org.ourproject.kune" with Main class: "com.google.gwt.dev.GWTShell", with this program arguments (or similar): "-noserver -out gwt-out /kune/?locale=en&log_level=INFO -port 8080" and in the "Classpath User Entries":
+* gwt-dev-[linux|mac|windows].jar (Add External Jar and choose it from your gwt installation directory)
 * java - /kune/src/main
 * kune (default classpath)
 
 If you have memory problems running the hosted mode, increase it in VM arguments:
-  -Xmx512M
+ -Xmx512M
 
 before run hosted mode compile once with:
  mvn gwt:compile
 and deploy with:
  script/deploy_gwt.sh 
-and then we run jetty (with "script/server.sh" also you can run server in debug mode, see TROUBLESHOOT).
+and then we run jetty (with "script/server.sh" also you can run server in debug mode, see TROUBLESHOOT). This is quite useful to put breakpoints in the server coe.
 
 ==Code preferences==
 
@@ -36,11 +147,17 @@
 please use it if you want to contribute.
 
 We will (try) to follow:
+
 http://code.google.com/webtoolkit/makinggwtbetter.html#codestyle
 
 and the code conventions for the JavaTM Programming Language:
+
 http://java.sun.com/docs/codeconv/html/CodeConvTOC.doc.html
 
+also we try to be a "Good Java Citizen":
+
+http://docs.codehaus.org/display/PICO/Good+Citizen
+
 ==Use of mylyn in eclipse==
 
 To use mylyn and to track the kune issues from eclipse, you have to add a "Web Repository" and select "ASM (gforge" with server: http://ourproject.org. 
@@ -54,14 +171,15 @@
 
 ==Code samples==
 
-See HelloWorldModule.java to a small sample of how to extend the gwt UI. 
+See HelloWorldModule.java to a small sample of how to extend the gwt workspace UI. 
 
 Check also trunk/HOWTO_ADD_A_NEW_TOOL to instructions of how to add a new tool in kune.
 
 ==Changelog==
 
 Periodically update the Changelog using svn2cl:
-
+ 
+ # In debian a related distros: 'apt-get install svn2cl' and do:
  svn2cl -i --authors=dev-utils/authors.xml -o ChangeLog
 
 ==License==
@@ -84,7 +202,7 @@
     along with this program.  If not, see <http://www.gnu.org/licenses/>.
 </pre>
 
-In Java, something like this (also you can use your name):
+In Java, something like this (you can put your name instead of "kune team" if you create new files):
 
 <pre>
 /*


