All pages: introduction message/location/muli format dtd xantlr tdom ops paisley metajava umod option auxiliaries d2d downloads & licenses people bibliography APPENDICES:: white papers white papers 2 white papers 3 project struct proposal SOURCE:option.dtd SOURCE:dtd.umod DOC:deliverables.ddf DOC-DE:deliverables.ddf DOC:mtdocpage.ddf DOC-DE:mtdocpage.ddf DOC-EN:lablog.ddf SOURCE:basic.dd2 DOC:xslt.ddf SOURCE:xslt.dd2 DOC:meta.ddf [site map]


white papers 3	bandm ^meta_tools

The ^meta_tools Project Structure, as a Proposal for User Projects

1          How to Employ ^meta_tools
2          The ^meta_tools Project Structure
2.1          Basic File System Layout
2.2          Standard Makefile
2.2.1          Standard Makefile --- Example
2.3          Files in etc
3          Employed Third-Party Tools
4          Using CVS and ssh

^{^ToC} 1 How to Employ ^meta_tools

This page presents a project structure as a proposal for a users' project, employing ^meta_tools .

It basically follows the project structure of ^meta_tools themselves.

^meta_tools come in one compact .jar file (see download page). The different tools as described in the other pages of this documentation can be used directly out of this, as usual.

Of course, you can

integrate ^meta_tools into an arbitrary (e.g. legacy) production context,
or create a project structure according to this proposal,
or at least take this proposal and the files contained therein as suggestions and additional documentation for your own a project design.
Whenever you are involved in the development of ^meta_tools themselves, the following design is mandatory anyhow.

There is some automated support for its creating and maintaining, as described on the doc page about auxiliaries. This is intended to be further developed in future.

^{^ToC} 2 The ^meta_tools Project Structure

This page presents a project structure as a proposal for a users' project, employing ^meta_tools .

It basically follows the project structure of ^meta_tools themselves.

There is some automated support for creating and maintaining, as described on the doc page about auxiliaries. This is intended to be further developed in future.

^{^ToC} 2.1 Basic File System Layout

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 $PRJ.

The sub-directories and their roles are ...

  <PRJ>/
       /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/ ... ???

Please note that if you want to use our make system in a windows/cygwin environment, the path down to <PRJ> must not containany directory names containing blanks/whitespace (cf. next section).

^{^ToC} 2.2 Standard Makefile

Our standard Makefile as residing in the directories below <PRJ>/src, relies on the following include relations:

   <PRJ>/src/XX/XX/XX/Makefile
          include <PRJ>/etc/Makefile.include
                  include <PRJ>/etc/config.mk
                  include <PRJ>/etc/calltools.mk

For the intial finding of <PRJ> there is a tiny but tricky function definition pasted into each Makefile. This function searches from "pwd" upward for a directory called "src". Therefore it only works correctly if no further directories named "src" appear in the path from <PRJ>/src/" down to Makefile, i.e. in the "XX/XX/XX" chain.

Furthermore, due to the string functions of "make", there must not be any directory containing blanks in its name above the project directory !

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 not appropriate for hosting your project.

For easy generating (skeletons for) all the Makefiles in the source tree there is a java program which is called by

java -classpath metatools.jar MakeMakefile .

It is documented on the doc page about auxiliaries.

Of course you can edit the generated Makefile afterwards (e.g. when the variable PACKAGE shall contain something different than the position of the sources in the file system). It will not be overwritten accidentially.

^{^ToC} 2.2.1 Standard Makefile --- Example

The following code shows a simplified and modified version of a Makefile really used in the ^meta_tools project:

# 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)

The list contained in $(SOURCES) will be passed to javac.
The list contained in $(GENSOURCES) contains sources, which must be generated themselves.
The files contained in $(INSTALL) will be copied into the class tree, as additional resources.

There are many standard rules defined in Makefile.include, but special rules may always be defined locally, as in the example the bootstrap rule for UMod.java.

^{^ToC} 2.3 Files in etc

In <PRJ>/etc all bash code, make code and configuration files are collected. The most important of the pre-defined program files are <PRJ>/etc/Makefile.include and <PRJ>/etc/calltools.mk.

The latter contains make macro definitions, each of them calling a certain component of ^meta_tools , after correctly formatting all required command line parameters from macro parameters and environment variables.

Then there is the central configuration file <PRJ>/etc/config.mk. Since this is different on every machine, there is a template <PRJ>/etc/config.mk.template, which shall be copied to the former and then edited.

The file 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.

(It is well documented, so it should be self-explanatory !-)

^{^ToC} 3 Employed Third-Party Tools

Each project employing ^meta_tools 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.

In detail we employ ...

java javac
java java
java jar
java/apache xalan (which internally uses xerces) Both are contained (invisibly!) in the java standard distribution.
gnu bash
gnu make
gnu sed
gnu curl

^{^ToC} 4 Using CVS and ssh

Only as a reminder, we finally show how to use CVS1 and how to generate an ssh key.

Checkout, update and commit:

cvs  -d:ext:<user>@<server>:<cvstopleveldir> checkout <project>
cvs  update -dAP 
cvs  commit -m "who am I and on which machine"

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!

This is done as follows:

(unix >)    ssh-keygen -trsa -b1024
(windows >) ssh-keygen.exe -trsa -b1024

Skip the "passphrase" by pressing return, because what we want to is not having to enter a bloody password each time we access the cvs.

If you do not specify a different file name, the program will create a file "$HOME/.ssh/id_rsa.pub".

Append the line from this file to the text file "$HOME/.ssh/authorized_keys" 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 !-)


white papers 3	bandm ^meta_tools

made 2024-08-30_18h00 by lepper on happy-ubuntu

produced with eu.bandm.metatools.d2d and XSLT FYI view page d2d source text

^ToC 1 How to Employ meta_tools

^ToC 2 The meta_tools Project Structure

^ToC 2.1 Basic File System Layout

^ToC 2.2 Standard Makefile

^ToC 2.2.1 Standard Makefile --- Example

^ToC 2.3 Files in etc

^ToC 3 Employed Third-Party Tools

^ToC 4 Using CVS and ssh