On Wed, May 7, 2008 at 3:34 PM, Linus Tolke <[EMAIL PROTECTED]> wrote:
> In order to attempt to straighten this out, I have written down some of > the results of the conversation in section 2.2 of the Cookbook. (Tomorrow > morning it will appear on the web site.) > For those who don't want to wait a day to see what it says, here's section 2.2. The new material begins after the large table and runs to the end of the section. Tom 2.2. Source layoutPrev<file:///C:/eclipse-workspace-blank2/argouml-documentation/build/documentation/defaulthtml/cookbook/ch02.html> Chapter 2. Building from source Next<file:///C:/eclipse-workspace-blank2/argouml-documentation/build/documentation/defaulthtml/cookbook/ch02s03.html> ------------------------------ 2.2. Source layout The development environment (source layout) of ArgoUML exists in two flavors: - The repository layout. - The Eclipse layout. The repository layout is used by the nightly build, when building releases, and when doing development that is not done within Eclipse. This is the traditional layout and the checkout procedure is described in Section 2.5, "Downloading from the Subversion repository"<file:///C:/eclipse-workspace-blank2/argouml-documentation/build/documentation/defaulthtml/cookbook/ch02s05.html>. The Eclipse layout is used when doing development within Eclipse. This was created to fit with Eclipse way of organizing projects. The checkout procedure is described in Section 2.9.3, "Checking out through Eclipse"<file:///C:/eclipse-workspace-blank2/argouml-documentation/build/documentation/defaulthtml/cookbook/ch02s09.html#eclipse-checkout>and controlled by Eclipse psf files. The table below show how the code is organized in the different layouts. *Table 2.1. Layout differences* CodeRepository locationThe repository layoutThe Eclipse layoutSubsystems http://argouml.tigris.org/svn/argouml/ trunk/src/*SUBSYSTEM-NAME* *WORK*/argouml/src/*SUBSYSTEM-NAME**WORKSPACE*/*SUBSYSTEM-NAME*Integration scripts for the core application http://argouml.tigris.org/svn/argouml/ trunk/src/argouml-build/* *WORK*/argouml/src/argouml-build/**WORKSPACE*/argouml-build/* (optional)Subsystems that are separate projects http://*PROJECT-NAME*.tigris.org/svn/*PROJECT-NAME*/ trunk *WORK*/*PROJECT-NAME**WORKSPACE*/*PROJECT-NAME*Integration resultN/A*WORK*/argouml/build or *WORK*/argouml/src/build?N/A Tools used for building and testing. This is the tools common to several subsystems. http://argouml.tigris.org/svn/argouml/ trunk/tools *WORK*/argouml/tools*WORKSPACE*/argouml-toolsTools used for release generation http://argoumlinstaller.tigris.org/ svn/argoumlinstaller/ trunk/* *WORK*/argoumlinstaller/N/ATools used for static checks http://argouml-gen.tigris.org/svn/argouml-gen/ trunk/tools *WORK*/argouml-gen/toolsN/A ???Documentation source http://argouml.tigris.org/svn/argouml/ trunk/documentation *WORK*/argouml/documentation*WORKSPACE*/argouml-documentationEclipse psf files http://argouml.tigris.org/svn/argouml/ trunk/www/psf *WORK*/argouml/www/psf (not used)*WORKSPACE*/psfEclipse templates (to use in the workspace or import into each project) http://argouml.tigris.org/svn/argouml/ trunk/tools/eclipse *WORK*/argouml/tools/eclipse (not used)*WORKSPACE* /argouml-core-tools/eclipseTools used for static checks http://argouml-gen.tigris.org/svn/argouml-gen/ trunk/tools *WORK*/argouml-gen/toolsN/A ???Src of released subsystem from core project http://argouml.tigris.org/svn/argouml/ releases/*RELEASE-TAG*/src/*SUBSYSTEM-NAME* *WORK*/argoumlinstaller/build/*RELEASE-TAG*/argouml/src/*SUBSYSTEM-NAME*N/A or *WORKSPACE*/*SUBSYSTEM-NAME* (if switched to)Src of released subsystem from other project http://*PROJECT-NAME*.tigris.org/svn/*PROJECT-NAME*/ releases/*RELEASE-TAG* *WORK*/argoumlinstaller/build/*RELEASE-TAG*/*PROJECT-NAME*/N/A or *WORKSPACE */*PROJECT-NAME* (if switched to) To handle the two layouts the following guidelines for writing ant scripts apply: - The same build.xml file is used, both for building from ant in the repository layout and in the Eclipse layout. - In argouml/src/*subsystem*/build.xml use ../*subsystem*/build/*name*to refer to files needed to compile and run tests. Only references to subsystems depended on are allowed. - argouml-core-model-mdr and argouml-core-model-euml depend on argouml-core-infra and argouml-core-model and no other. - argouml-app should in the orthodox world depend only on argouml-core-infra and argouml-core-model. It depends also on argouml-core-model-mdr but only for running tests but that is because the tests are integration-level tests instead of tests for that subsystem. - argouml-core-diagrams-sequence2 and all other diagrams subsystems depend on argouml-core-infra, argouml-core-model, and argouml-app. - The "jar" target in argouml/src/*subsystem*/build.xml compiles the code, creates the directory build within *subsystem*, and copies all exported jars there. Since this build depends on jars in depended on subsystems, the target should first run the "jar" target in those subsystems. Also jars that are not generated but provided by the subsystem are copied. - In the repository layout, the "package" target in argouml/src/argouml-build/build.xml compiles all subsystems, creates the directory build in argouml/src/argouml-build and copies all exported jars from all subsystems there. The copying only copies files and not directories. For that reason make sure everything that is exported is in files and everything that is not exported in directories. Especially generated java files, the class files as results of the compilation of source and tests, test results, javadoc report, and other generated reports shall be generated in directories to avoid being included in the release. - In the Eclipse layout, the "package" target in argouml-build/build.xml(same as above) compiles all subsystems, creates the directory ../argouml/build and copies all exported jars from all subsystems there. For this reason no Eclipse project shall be name "argouml". - For Modules that are developed in separate Tigris projects in the argouml-*name*/build.xml file use ../argouml/build/*name* to refer to files needed to compile and run tests. Only references to subsystems depended on are allowed. Modules should probably depend on argouml-core-infra, argouml-core-model, and argouml-app and not anything else. - The "jar" target in argouml-*name*/build.xml compiles the code, creates the directory argouml-*name*/build, and copies all exported jars there. - The "install" target in argouml-*name*/build.xml performs the "jar" target and copies all jars needed by the deployed application to ../argouml/build/ext. The release script includes the files from there. - For the listed purposes, use the paths listed in the table, in all subsystems and modules. *Table 2.2. Created things* WhatWhere (under ./build) Result of the compilation of src/*tree* and build/java/*tree* classes/*tree* Result of the compilation of tests/* tree* tests/classes/*tree* Generated java codejava/*tree*XML result from tests tests/reports/junit/output/*XML-files* HTML result from tests tests/reports/junit/output/html/*HTML-files* Complete javadoc reportjavadocsJavadoc report exported functions onlyapi Instrumented classes from build/classes/*tree* instrumented/*tree* - Tools that reside in the tools directory are referenced using the property argo.tools.dir. Like this: ${argo.tools.dir}/*path to the file* The tools in question are the tools used for build and testing that are common to several subsystems. - Every build.xml file that uses tools from the tools directory shall set the argo.tools.dir property. This is done by testing for the existance of the *candidate-dir* /checkstyle/java.header file and the result should be set to: - ../../tools for subsystems in the repository layout. - ../argouml-core-tools for subsystems in the Eclipse layout. - ../../tools for argouml-build in the repository layout. - ../argouml-core-tools for argouml-build in the Eclipse layout. - ../tools for documentation in the repository layout. - ../argouml-core-tools for documentation in the Eclipse layout. - ../argouml/tools for other Tigris projects in the repository layout. - ../argouml-core-tools for other Tigris projects in the Eclipse layout. The reason for setting this explicitly everywhere is to reduce the amount of dependencies to a certain file or files and removes need to have that file available to calculate the paths. If the location of the tools directory will every change, there will be a major problem updating all projects.
