![](http://www.gnu-darwin.org/hexley-gd-sm.png)
|
gtgt
gitty-gitty
The General/GNU Template Generation Tools
version <#1.3.2#>
(0) Content of this Explanation
copyright (c) 2000/2001/2002 karsten reincke
(karsten@karubik.de)
The (general | GNU) template generation tools are a set of scripts
for creating a whole set of sources, which may already be
compiled and installed by using the GNU development tools.
Think of gtgt as a program which is able to create an already
compilable, very sophisticated "hello world" program, written
in C or C++ and constituted by a main program,
two internal modules (classes), one static and one shared library. Using gitty-gitty
you will get a template of sources for the main cases you
might meet, and which you can also use as examples for automake, autoconf and so on.
For understanding the general purpose of the
(general | GNU)-template-generation-tools, we should have a look
at an abbreviated version of the history of programming
with gcc:
- At the beginning we have nothing but gcc:
we have to order each act of compilation with regards to name the right versions
of sourcecodes on the command-line. (practical, but not comfortable)
-
The next step in evolution is "MAKE", now we are not only able
to create scripts for compiling more than one set of sources, but now
we can demand to respect dependencies. (comfortable, but not
the end of the world)
-
Then there has been the problem to compile for more than one specific
hardware environment. And this problem leads to the solution by using
autoconf: We are setting up two scripts, configure.in and
Makefile.in. In the first one we determine in a declarative
way those aspects, which we want to have tested. Then we call
the tool 'autoconf' which takes the configure.in scripts and
creates the well known configure script. This script itself
takes the makefile.in, tests the environment and replaces
variables in the makefile.in by the test-results and
creates the normal makefiles, which are now very sophisticated.
But at this point of history, we only have to create the configure.in
and the makefile.in, and we can use informations about the hardware
used for the compilation, by writing variables into our makefile.in
(a bit better, but still optimizable)
-
"Why" - so the next question - "shouldn't it be possible to use
a high-level declarative language for saying what we want to compile
instead of using the old makefile-language?" The answer has been
automake. This script takes Makefile.am
and configure.in and creates Makefile.in.
and as software-developpers we now only have to write our intentions into Makefile.am
and configure.in. (the world seems to be good, but not the best
of all possible ones)
-
The GNU development tools demand a lot more files than Makefile.am
and configure.in: One has to touch at least NEWS, Changelog, Install,
README ..., and you have to create a directory structure.
For automating this procedure, autotools have been offered:
Here you may create a whole but empty environment for the GNU
development tools and you have a tool to generate files containing a copyright-note.
(This major step has been
done by
Eleftherios Gkioulekas) (yoop, yoop, but then ...)
-
There are two demands, which can't be fullfilled by autotools. If you
want to have your own licenses in your sources, you can't use autotools
because they only offer GNU files and -conditions. Ok, GNU is quite fine,
but it's not everything. And although you are using autotools you still have to
declare and define all functions inside of your sources and you
need to setup the correct Makefile.am and configure.in in a corresponding way.
That can be automised too - at least for a starting version.
And that's the task of the
(general | GNU) template generation tools. They are able to replace the
autotools and contain three scripts:
gcng, gscg and gptg.
- gcng = General Copyright Note Generator
-
Script of generating files, which already contain the correct
copyright header, regardless of which copyright and
which programming language shall be used
- gscg = General Source Code Generator
-
Script for generating all already compilable source files of
a software module, namely the header file as a module declaration
and the source file as a module defintion.
You can select c or c++ as the programming-language, which is
used for writing these functions. Think of gscg as a program, which is
able to create very sophisticated "hello world" modules.
- gptg = General Project Template Generator
-
Script for generating the whole set of files for an already
compilable and installable software project: Using gscg
+ gcng too, gptg will offer a project directory, which is
completely prepared for utilisation of autoconf and automake
and which contains a quite sophisticated "hello world" program
- being built upon two modules and one static library -
and which already offers a
shared library.
Using these tools (which are using themselves too), you get a template,
which only needs to be adopted to what you want to have.
For being able to install and use the gtgt you need
- Normal gcc development tools (normally you are already having them)
- autoconf
- automake
- libtools
For installing the gtgt you do the following:
- gunzip gtgt-xxx.tgz
- tar -xvf gtgt-xxx.tar
- cd gtgt-xxx
- ./configure --prefix=/whereever/youwant/tohave/thetools
- make
- su
- make install
Note: It's not nescessary to have autoconf and automake for installing gtgt
but for using it, because adding a new piece of sourcecode includes modification of
Makefile.am (and configure.in). And in all those cases you need to call automake and
autoconf at least one time, before being able to call configure for the set.
Create a short project name like 'mypo', which should not contain blanks or
other seperators. Think of it as a name, not as a double name or
sentence or anything else. Following the c/c++-coding-standard this name will
automatically be changed in some cases: he can be capitalized or written in
lower or upper cases.
Decide, whether you want to use C or C++ as a programming-language.
(If you only want to write shell scripts, you may choose any of these.)
Decide with which main release number you want to begin. Usually
you start with zero (select an integer like 1,2,3, not any real or float number
like 1.2 and so on)
Decide with which revision number you want to begin. Usually
you start with one (select an integer like 1,2,3, not any real or float number
like 1.2 and so on)
Type 'gptg --help' to see in which way these decisions can be inserted
into gptg:
gptg |
OPTIONS |
[PROJECT] |
[RELEASE] |
[REVISION] |
|
-h, --help, -v, --version, -cpp (Language C++), -c (Language C) |
projectname |
start release number |
start release branch number |
-
gptg uses gscg and gscg uses gcng. gcng itself needs a file
gcng.conf in the working-directory. This file contains 6 lines:
- The authorname
- The email adress of the author
- The year of publishing the program (will be inserted automatically)
- The name of the company licensing the sources
- The absolute path to a short version of the company's license
- the absolute path to a long version of the company's license
If this file doesn't exist, you will be asked for the informations
and it will be created. If your company is GNU, you won't be asked
for licenses, because they are known. If not, you have to create
such licenses. They will be used automatically for generating
sourcecode headers. Examples for those company licenses
can be found in the documentation directory of the gtgt,
which will be installed under $PREFIX/share/doc/gtgt.
user@computer> gptg -cpp mypo 0 1
will generate a project named mypo, positioned in a directory mypo-0.1
Note: After changing into your project directory, you can already type ./configure, make, make distcheck,
or make install. You have a project which at first installs one application named like your project and
made to modules and which installs two libraries as a second step, a static and a shared one. You now have
to adopt these possibilities to your whishes and you can use this automatically generated project
as a teaching example to handle autoconf and configure.in, automake and Makefile.am and configure.in
while working at your own specific project. Because the sources are following the c/c++ coding standard
and are already commented in the doxygen style, you can take them as teaching examples for these aspects, too.
(4.2)
The configuration file gcng.conf and what the hell does "company license" mean?
Ok, GNU is good. Very good, that is. But [ in very rare cases ;-) ] it's not evrything.
Therefore, for example, the LGPL has been created. Well, you should be able to create
applications following the GNU methods and GNU recommendations
and using the GNU tools - without publishing your results under the GPL.
In these cases you might want to distribute your sources under a special company license.
And this license should be referred to by all your files.
GNU uses the following way to mark the GNU sources as GNU sources:
- Inside of the project directory, there the whole GNU license is given to the user
who gets a source tarball for creating an application from the sources. This license
can be found in the file COPYING.
- Each sourcefile contains a short version of this license by listing up
the main points of the whole license and refering to file COPYING or the GPL
- Sometimes it's necessary to publish special parts of the tarball under a weaker license
than the other parts. For example remember the LGPL: In these cases such (library-)sources
contain a special hint.
Think of the company license as a special "GNU license" of your company ;-). And therefore you should
have two versions: The long version is that one, which shall be put into the file COPYING, and the short
is that one, which will be used inside of the the files and which should refer to the long version.
The last question could be this: How can I determine, to create a template for my company
or for the GNU world? the answer is very simple:
- If you insert the word GNU in the fourth
line of the gcng.conf file, line 5 and 6 will be ignored and the normal GNU licenses will be
inserted for case (1) and (2) of the above mentioned list.
- If you insert a different word than GNU in the fourth line of gcng.conf, line 5 and 6 will
be evaluated as absolute pathnames of your company license files: line 5 as pathname
of the abbreviated version, line 6 as pathname of the long version.
The gtgt-tarball offers two license examples inside the doc-directory: the file
"company-license.long" and the file "company-license.short". Note: They haven't been
juristically checked! They exist for demonstrating the technical possibilities.
(4.3)
What if I want to build my tarball with more or other sourcefiles than given by the gptg script?
Very simple, in the first part of the following chapters, we explain what
you should do, if you don't want to use the full set of files. And in the
second part we explain, what you need to do, if you want to expand set files.
Read ${YOURPRJ} as a name of your project:
- Change into the toplevel of your project directory
- Delete the substring 'lib/Makefile' as parameter of the macro AC_OUTPUT in the file 'configure.in'
- Delete the directory 'lib'
- Delete the substring 'lib' as parameter of the macro SUBDIRS in the file 'Makefile.am'
- Change into the subdirectory src of your project directory
- Delete the substring '-l ${YOURPRJ}_stli' as parameter of the macro ${YOURPRJ}_LDADD
in the file 'Makefile.am'
- Delete the substring '-L$(topbuilddir)/lib' as parameter of the macro ${YOURPRJ}_LDFLAGS
in the file 'Makefile.am'
- Delete all lines containing the substring '_stli' in the source-files
${YOURPRJ}.c(pp)
- Call autoconf and automake or your reconf script
- change into the toplevel of your project directory
- Delete the substring 'src/damo/Makefile' as parameter of the macro AC_OUTPUT in the file 'configure.in'
- Change into the subdirectory src of your project-directory
- Delete the substring 'damo' as parameter of the macro SUBDIRS in the file 'Makefile.am'
- Delete all lines containing the substring 'damo' in the source-files
${YOURPRJ}.c(pp)
- Delete the directory 'damo' in your src-directory
- Call autoconf and automake or your reconf script
- Delete the libraries like described above
- Change back into the toplevel of your project directory
- Delete the substring 'src/Makefile' and 'src/damo/Makefile' as parameter of the
macro AC_OUTPUT in the file 'configure.in'
- Delete subdirectory src of your project directory
- Delete the substring 'src' as parameter of the macro SUBDIRS in the file 'Makefile.am'
- Call autoconf and automake or your reconf-script
Sister modules are sources with a declaring headerfile and a defining sourcefile
physically lying in the same directory of the main sourcefile and being included.
For generating such a module you may do this:
-
Change into the subdirectory src of your project directory
-
Call gscg and insert the parameters:
gscg |
[-c|-cpp|-h|-v] |
[-i|-s|-is] |
[MODULE] |
[PROJECT] |
[RELEASE] |
|
Select your programming language or 'help' or 'version' |
- -i echos the corresponding headerfile
- -s echos sourcecode for the module
- -is writes include- + sourcecode as file
|
should be a short module identifier without brackets, underlines, points etc. etc. |
should be a short project identifier without brackets, underlines, points etc. etc. |
release number (must be a float with two digits like 1.0 !!!) |
user@mashine > gscg -cpp -is modu mypo 1.0 creates mypo.h and mypo.cpp
-
Include ${MODULENAME}.cpp and ${MODULENAME}.h in Makefile.am as arguments of ${YOURPROJECT}_SOURCES
- Change back to the top of your project directory and call autoconf and automake or your reconf script
- Then write and include your module / class
Nearly the same as for adding a new sister module.
But act in the library directory instead of the source directory.
Nearly the same as for adding a new sister module. After having determined the library name
(=module name) you need to insert the following into the Makefile.am of your lib-directory:
- lib_LIBRARIES=lib${modulename}.a
- lib${modulename}_a_sources= $your-sources
- Don't forget to insert the new library name in src/Makefile under ${YOURPROJECT}_LDADD
as a string starting with -L
- Move the scripts and documentation files into the director doc respectively scripts
- Change into the subdirectory doc resp. scripts of your project directory
- Add the filenames of the new scripts to the variable EXTRA_DIST of Makefile.am .
In case of shell-scripts, add the name also to the variable bin_SCRIPTS
and to CLEANFILES and insert any makefile target for those scripts.
The VPATH variable allows us to use other directories whose content is able
to fulfill the dependencies although it's not directly integrated into
the 'make' procedure. Using this variable, one can split the objectfiles
and its sources. From make's point of view, it's a hack. But not all hacks
are bad, aren't they?. Ok, do this (and write me, if you are sucessful ;-) ):
- Change into the top of your project directory
- Rename the subdirectory src into vpdir (or anything else)
- Rename all those substrings 'src' into vpdir, which arise as contents of the variable
SUBDIRS in the main Makefile.am
- Insert a new substring src into the content of the variable SUBDIRS in the main Makefile.am
- Create a new subdirectory src
- mv all sources vpdir/*.cpp *.c *.h from vpdir into the new directory src
- Change into the new src directory
- Edit a new src/Makefile.am
- Insert into this src/Makefile.am the only variable EXTRA_DIST= $all-names-of-your-moved-sources
- Insert into each Makefile.am arising in any directory under vpdir or lib the string
VPATH=$(top_srcdir)/src.
The main point of this procedure is this: make recursively follows the structure of vpdir.
There maket meets its targets. And it seeks the sources, named inside of the Makefile and
not really being in the make directory. But make finds them none-the-less, because it looks
for them in all directories named by the variable VPATH which in this case is
indicating the directory source as an add-on
Last but not least, we have added the doxygen documentation style into the automatically
generated sourcefiles of your project initially created by the gitty-gitty-tools. This includes that
- the correspondig default doxygen configuration file (named Doxyconf)
will automatically be generated inside of the project-directory
- all pieces of sourcecode are already be commented in the doxygen style
- the initial version of corresponding doxygen sourcecode documentation
will be automatically generated while creating the initial version of your project
- the whole sourcecode doxygen documentation of the initial-version of your project
can be found under doc/doxygen/
For being generally acceptable, we have adopted the c++ and c coding standard. But note:
There doesn't exist "the coding standard"; you can find more than one which
differ in more or less details. Therefore we give only one hint for a
C++ Coding Standard
while recommending to have a look at the others, being found with some search engine.
Last but not least we have integrated a script into the GNU-sourcetree which
allows the change of the release- and the revisionnumber.
Remember, if you let create the template of your project you have to name integers for the
release and the revision on the commandline. these numbers will be merged
into many places: for example into the short copyright line of each piece
of sourcecode where the name of the file and that of the project is also
announced.
But there exist more important places where these numbers are inserted. There they will
be evaluated for generating the tarball-number or the library-version. For updating
all these case with one command gptg writes a script into your project-direcgtory.
This script named change-release does what its name announces:
it should be called with one
or more file- or directorynames (or with *) as parameter. and for all these entities
it recursively changes all relevant release/revision numbers.
For using this script you have to respect the following points:
- You shouldn't change the release/revision-strings manually. or at least
you have to respect the given syntactically structure.
- If you want to increment (decrement ?-) ) the revison/release-number
you have to edit the script change-release: insert
the correct old versions of the numbers and the wished new versions
at the beginning of the script and then call ./change-release
- Note, change-release isn't backward compatible. if
you want to use it in an existing project (made by GTGT release 1.1
or earlier) you have to recreate
it. and if you merge older pieces of sourcecode into that new
tree you have at least to replace the short-copy-right line
which signals filename, project and version-number
Note: In the string "-version-info xc:xr:xa" ,
which arises in the «Makefile.am» and is updated by the script
«changerelease», the integer at the position «xc»
means «current release», the integer at the position
«xr» «revision» and the integer at the postion
«xa» the «age» of the library. And the age of a
library denotes the row of elder releases, which interfaces all only
are expanded by the newer ones.
But this row of integers "xc:xr:xa" arises not directly in the version
of a shared library. You have to read such versionnumbers like the
scheme «libxxx-so.xc.xa.xr»: the first integer of a
library-version number denotes the current release, the second the age(!)
and the third the the revision number.
In each Makefile.am GTGT offers now four different lines with compiler flags:
- In a Makefile.am for c++-programs
-
- CXXFLAGS = -DLinux -Wall -ansi -pedantic
- #CXXFLAGS = -DLinux -Wall -ansi -pedantic -g
- #CXXFLAGS = -DLinux -Wall -ansi -pedantic -O3
- #CXXFLAGS = -DLinux -Wall -ansi -pedantic -g -pg
- In a Makefile.am for c-programs
-
- CFLAGS = -DLinux -Wall -ansi -pedantic
- #CFLAGS = -DLinux -Wall -ansi -pedantic -g
- #CFLAGS = -DLinux -Wall -ansi -pedantic -O3
- #CFLAGS = -DLinux -Wall -ansi -pedantic -g -pg
So, if you want to add debug infos,
uncomment line 2 after having commented line 1.
If you want to add debug and profiling infos,
uncomment line 4 after having commented line 1.
And if you want to use optimized code,
uncomment line 3 after having commented line 1.
If you import a more or less elaborated project into a cvs repository,
you must pay attention not to import binary files as text and not
to import those files, which can be derivated from other by using
any program. And you should have a file «.cvsignore»
in each directory by which you can evoke cvs to ignore those
derivatable files.
Beginning with release 1.3.0 gtgt offers a shell script
«prepare-cvs-import», by which
you can erase all derivatable files out of your working tarball:
Using the command «make distclean» all libs, object-files
and applications will be deleted (because they can be regenerated by the pair
«./configure make»). And then all files and links will be deleted
which can be regenerated by calling «./reconf , autoconf, automake and
./configure». Therefore you can type «cvs import ...»
after having typed «./prepare-cvs-import» without thinking
about which file you should import and which not.
If you have generated a tarball being cleared for cvs import (either by calling
«./prepare-cvs-import» or by typing «cvs co ...», which
naturally can't offer other than imported files), you must type
for getting back the status before having type «./prepare-cvs-import»
you can find more hints inside of the tarball.
Feel free to contact reincke@icdm.de
or at karsten@karubik.de.
you are strongly encoraged to correct, to suggest, to wish ...
For general informations have a look at http://www.icdm.de/
and http://www.karubik.de/karsten/
too.
It's a great pleasure for me to thank some people:
-
Christian Heissing as first user and tester of the gitty-gitty-tools who
has good eyes for finding improvable aspects
- Guido Sassmannshausen as first
reader of the documentation who worked
hard to correct my english. (For any still existing fault I am
responsible not he !!!)
-
Eleftherios Gkioulekas
as developper of the autotools which have been the basis of the
gitty-gitty-tools.
-
Ralph Schunk, who has pointed to the correct use of some new libtool macros.
-
My company ICDM
which uses gtgt and has evoked some improvements
|