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          Projects using ^meta_tools with GNU make
2.1          Basic File System Layout
2.1.1          File Name Caveats With Windows
2.1.2          Automated Creation of the Directory Structure
2.2          Standard Makefile
2.3          Files in etc
3          Projects using ^meta_tools with Maven
4          CheatSheet: Using CVS and ssh

^{^ToC} 1 How to Employ ^meta_tools

^meta_tools as a binary distribution 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.

You can

integrate parts of ^meta_tools , or parts thereof, into an arbitrary (e.g. legacy) production context,
or create a project structure according to the following proposals,
or at least take the proposals and the files contained therein as suggestions and additional documentation for your own a project design.

Currently we have experience with two fundamentally different project structures, both having their pros and cons.
(Regrettably there are no experiences yet with ^meta_tools and IDEs.)

^{^ToC} 2 Projects using ^meta_tools with GNU make

This section proposes a structure for a users' project, employing ^meta_tools and GNU make. It basically follows the project structure of ^meta_tools themselves.

Beside make it uses furhter standard Unix tools, like sed and bash. (Please ensure that bash is present on your system and entered correctly in the configuration file. Other shell variants may possibly not work correctly)

^{^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
            \______________________/
           package prefix mapped to the
           file system, as usual in Java

       /lib
       /lib/Makefile 
       /lib/<FINAL_PRODUCT>.jar
       /lib/<IMPORTED_LIB>.jar

       /lib/classes      // javac output and installed resources
       /lib/classes/domain
       /lib/classes/domain/subdomain
       /lib/classes/domain/subdomain/package
       /lib/classes/domain/subdomain/package/Source1.class
       /lib/classes/domain/subdomain/package/Source1$1.class
       /lib/classes/domain/subdomain/package/Source1$2.class
       /lib/classes/domain/subdomain/package/Source2.class
                    \______________________/
                   package prefix mapped to the
                  file system, as usual in Java

       /etc               // configuration data and macro functions
       /etc/Makefile.include
       /etc/config.mk.template
       /etc/config.mk
       /etc/config.const
       /etc/calltools.mk

       /doc
       /doc/api
       /doc/makeapidoc/Makefile
       /doc/usage
       /doc/usage/Makefile
       /doc/usage/additionals.mk

^{^ToC} 2.1.1 File Name Caveats With Windows

Please note that if you want to use our make system in a windows/cygwin environment, the path down to <PRJ> must not contain any directory names containing blanks/whitespace (cf. next section), as it is common in the Windows world.
Contrarily, Windows systems cannot treat correctly with file names which are only distinguishable by case. Since this is currently necessary for "SRC" vs. "src", metatools themselves cannot be built on an Windows file system.

^{^ToC} 2.1.2 Automated Creation of the Directory Structure

For easy generating this file structure and the skeletons for all the Makefiles in the source tree there is the program StartApplicationProject_makeBased. It can be called by

mydir$ java -classpath metatools.jar eu.bandm.tools.applicationStart.startApplicationProject_makeBased  domain.subdomain.package

to create the structure depicted above.

The current working directory when calling this application is the point where the project tree will be installed. All necessary files will be copied into the new tree.

Once created, your must edit the generated Makefile, e.g. fill in the names of the Java sources, and you can (and must) edit most of the generated files.

But some files have a warning text in their very first line which tells you not to edit them, because this can jeopardize the functionality of the make system.

After creation, the ^meta_tools make system will never overwrite any of these files. (But some tools which generate source files do overwrite "package-info.java" !)

Of course, further branches can be added to the "tree", which is created more like a "bare stem".

^{^ToC} 2.2 Standard Makefile

Our standard Makefiles as residing in the directories below <PRJ>/src, relie 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 contained in each Makefile which searches the directory tree upwards for the marker file .prjroot.

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

# umod Makefile 
PACKAGE := eu.bandm.tools.umod

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

findprj=$(if $(wildcard $1/.prjroot),$1,\
	$(call findprj,$(patsubst %/,%,$(dir $1))))
PRJ=$(call findprj,$(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.

The fundamental philosophy fot the configuration data is (a) to make it text based and explicit, and (b) to keep it centrally, in only two files.

Configuration data falls into these categories:

(a) Scalar values,
(b) global URIs,
(c) relative file system references, internal to the project's file tree,
(d) file system references which depend on the particular compilation environment and leave the projects file tree.

Examples are: (a) "JAVA_PARAMS" (b) "JAVA_ONLINE_API_DOC" (c) "ICON_16X16" (d) "JAVA_SE_BINARIES".

The data (a) to (c) is specific for a particular project, but independent from the compilation environment and is kept in the single file config.const.
It can be checked into the underlying document management systemlike CVS.

For the data (d) there is the configuration file <PRJ>/etc/config.mk. Since this is different on every machine, there is a common template <PRJ>/etc/config.mk.template, which shall be copied and edited.

The generated templates are well documented, so they should be self-explanatory.

^{^ToC} 3 Projects using ^meta_tools with Maven

A very different approach is to use Maven.
MORE TO COME

^{^ToC} 4 CheatSheet: 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 2025-01-08_22h19 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 Projects using meta_tools with GNU make

^ToC 2.1 Basic File System Layout

^ToC 2.1.1 File Name Caveats With Windows

^ToC 2.1.2 Automated Creation of the Directory Structure

^ToC 2.2 Standard Makefile

^ToC 2.3 Files in etc

^ToC 3 Projects using meta_tools with Maven

^ToC 4 CheatSheet: Using CVS and ssh