#d2d 2.0 text using mtdocpage : webpage #title The #mt Project Structure, as a Proposal for User Projects #htmlTitle bandm metatools: Proposal for User Projects #lang en #tableOfContents // ------------------------------------------------------- #h1 #title How to Employ #mt // ------------------------------------------------------- #p This page presents a project structure as a proposal for a users' project, employing #mt/. #p It basically follows the project structure of #mt themselves. #p #mt come in one compact #src!.jar! file (see #link getit.html #text download page#/link). The different tools as described in the other pages of this documentation can be used directly out of this, as usual. #p Of course, you can #list #i integrate #mt into an arbitrary (e.g. legacy) production context, #i or create a project structure according to this proposal, #i or at least take this proposal and the files contained therein as suggestions and additional documentation for your own a project design. #p Whenever you are involved in the development of #mt themselves, the following design is mandatory anyhow. #p There is some automated support for its creating and maintaining, as described on the doc page about #link auxils.html #loc txt_metatoolsmetatools #text auxiliaries#/link. This is intended to be further developed in future. // ------------------------------------------------------- #h1 #title The #mt Project Structure // ------------------------------------------------------- #p This page presents a project structure as a proposal for a users' project, employing #mt/. #p It basically follows the project structure of #mt themselves. #p There is some automated support for creating and maintaining, as described on the doc page about #link auxils.html #loc txt_metatoolsmetatools #text auxiliaries#/link. This is intended to be further developed in future. // ------------------------------------------------------- #h2 #title Basic File System Layout #p The basic file system layout is one connected sub-tree of a local file system. The root of this sub-tree is referred to by the variable #src!$PRJ!. #p The sub-directories and their roles are #ldots #commentchar \ \* ================================== #source | etc // configuration data | lib // binaries, read and written | | classes // output from javac | | | eu // ----------------+ | | | | comp // | url part of class names, | | | | | prod // | mapped to the file system | | | | | | part // | as usual with java projects. | // contains "x.class" | | | src // sources | | eu // ----------------+ | | | comp // | url part of source file names, | | | | prod // | mapped to the file system | | | | | part // | as usual with java projects. | // contains "x.java" #/source #p An abstract example: ==================================== *\ #source / /src/ // sources (mostly java and meta-tools sources) /src/Makefile /src/domain/ /src/domain/Makefile /src/domain/subdomain/ /src/domain/subdomain/Makefile /src/domain/subdomain/package/Makefile /src/domain/subdomain/package/Source1.java /src/domain/subdomain/package/Source2.java /lib /lib/Makefile /lib/FINAL_PRODUCT.jar /lib/IMPORTED_LIB.jar /lib/classes // binaries, compiler output and installed resources /lib/classes/domain /lib/classes/domain/subdomain /lib/classes/domain/subdomain/package /lib/classes/domain/subdomain/package/Source1$1.class /lib/classes/domain/subdomain/package/Source1$2.class /lib/classes/domain/subdomain/package/Source2.class /etc // configuration data and macro functions /etc/Makefile.include /etc/config.mk.template /etc/config.mk /etc/calltools.mk /doc /doc/api /doc/api/Makefile /doc/ ... ??? #/source #commentchar / #p Please note that if you want to use our make system in a windows/cygwin environment, the path down to #src!! #bold must not contain#/bold any directory names containing blanks/whitespace (cf. next section). // ------------------------------------------------------- #h2 #title Standard Makefile #p Our standard #src!Makefile! as residing in the directories below #src!/src!, relies on the following include relations: #source /src/XX/XX/XX/Makefile include /etc/Makefile.include include /etc/config.mk include /etc/calltools.mk #/source #p For the intial finding of #src!! there is a tiny but tricky function definition pasted into each #src!Makefile!. This function searches from "#src!pwd!" upward for a directory called "#src!src!". Therefore it only works correctly if no further directories named "#src!src!" appear in the path from #src!/src/!" down to #src!Makefile!, i.e. in the "#src!XX/XX/XX!" chain. #p Furthermore, due to the string functions of "make", there must not be any directory containing blanks in its name above the project directory ! #p This is important to observe esp. under windows, using cygwin. windows users and designers seem to love file names with whitespace! E.g. "Documents and Settings" is #emph!not! appropriate for hosting your project. #p For easy generating (skeletons for) all the Makefiles in the source tree there is a java program which is called by #source java -classpath metatools.jar MakeMakefile . #/source #p It is documented on the doc page about #link auxils.html #loc txt_metatoolsmetatools #text auxiliaries#/link. #p Of course you can edit the generated Makefile afterwards (e.g. when the variable #src!PACKAGE! shall contain something different than the position of the sources in the file system). It will not be overwritten accidentially. // ------------------------------------------------------- #h3 #title Standard Makefile --- Example #p The following code shows a simplified and modified version of a #src!Makefile! really used in the #mt project: #commandchar ! !source # umod Makefile SUBDIRS = parser absy runtime TRAVERSAL = ${POSTORDER} SOURCES := SOURCES += Main.java SOURCES += Reducer.java SOURCES += Checker.java # ..... etc. ... GENSOURCES := GENSOURCES += UMod.java GENSOURCES += Options.java GENSOURCES += GuiOptions.java SOURCES += $(GENSOURCES) INSTALL := INSTALL += original.dtd PACKAGE := eu.bandm.tools.umod findprj=$(if $(subst src,,$(notdir $1)),\ $(call findprj,$(patsubst %/,%,$(dir $1))),$1) PRJ=$(dir $(call findprj,$(shell pwd))) include $(PRJ)/etc/Makefile.include UMod.java: UMod_BOOT.java cp $< $@ Options.java: umodOptions.xml $(PRJ)/src/eu/bandm/tools/option/.compiled $(call options2java, $<, $(PACKAGE), Options, GuiOptions, $(PRJ)/src) !/source !commandchar # #p The list contained in #src!$(SOURCES)! will be passed to #src!javac!. #nl The list contained in #src!$(GENSOURCES)! contains sources, which must be generated themselves. #nl The files contained in #src!$(INSTALL)! will be copied into the class tree, as additional resources. #p There are many standard rules defined in #src!Makefile.include!, but special rules may always be defined locally, as in the example the bootstrap rule for #src!UMod.java!. // ------------------------------------------------------- #h2 #title Files in #src!etc! #p In #src!/etc! all bash code, make code and configuration files are collected. The most important of the pre-defined program files are #src!/etc/Makefile.include! and #src!/etc/calltools.mk!. #p The latter contains #src!make! macro definitions, each of them calling a certain component of #mt, after correctly formatting all required command line parameters from macro parameters and environment variables. #p Then there is the central configuration file #src!/etc/config.mk!. Since this is different on every machine, there is a template #src!/etc/config.mk.template!, which shall be copied to the former and then edited. #p The file #src!config.mk! must contain (1) paths to the positions in the file system of required third-party libraries and tools, and (2) settings of certain switches which influence the generating process of code and documentation. #p (It is well documented, so it should be self-explanatory !-) // --------------------------------------------------------------------- #h1 #title Employed Third-Party Tools #p Each project employing #mt needs, of course, (1) some GNU software, (2) some open source and public domain software under different, but similar licenses, and (3) a java SDK. #p In detail we employ #ldots #list #i java #src!javac! #i java #src!java! #i java #src!jar! #i java/apache #src!xalan! (which internally uses #src!xerces!) Both are contained (invisibly!) in the java standard distribution. #i gnu #src!bash! #i gnu #src!make! #i gnu #src!sed! #i gnu #src!curl! #/list // --------------------------------------------------------------------- #h1 #title Using CVS and ssh #p Only as a reminder, we finally show how to use CVS1 and how to generate an ssh key. #p Checkout, update and commit: #source cvs -d:ext:@: checkout cvs update -dAP cvs commit -m "who am I and on which machine" #/source #p When using CVS, it is much more convenient to put an ssh key on the server. Then you do not have to type your password every time! #p This is done as follows: #source (unix >) ssh-keygen -trsa -b1024 (windows >) ssh-keygen.exe -trsa -b1024 #/source #p Skip the "passphrase" by pressing return, because what we want to is #emph!not! having to enter a bloody password each time we access the cvs. #p If you do not specify a different file name, the program will create a file "#src!$HOME/.ssh/id_rsa.pub!". #p Append the line from this file to the text file "#src!$HOME/.ssh/authorized_keys!" #bold on all host computers you want to access, #/ and all ssh log-ins (including CVS interactions) will from now on work without manual password input. Great !-) The only thing you should care for from now on is to keep the access to THIS computer well locked !-) #eof