copyright (c) 2000/2001/2002/2003/2004/2005/2006/2007 karsten reincke (karsten.reincke@fodina.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:
Script of generating files, which already contain the correct copyright header, regardless of which copyright and which programming language shall be used
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.
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
For installing the gtgt you do the following:
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:
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 1will 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.
Ok, GNU is good. Very good, indeed. 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:
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:
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.
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:
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' |
|
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
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:
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 ;-) ):
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
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:
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:
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 files by using any program. For CVS-repositories you should have a file «.cvsignore» in each directory by which you can evoke cvs to ignore those derivatable files. For Subversion-repositories you should have expanded the svn:ignore-feature by those file-names and/or patterns which shall be ignored. With gtgt it is not nescessary to do this by yourself:
Beginning with release 3.0.0 gtgt offers a shell script «prepClearRepCommit.sh» which realizes the following aspects:
If you have generated a tarball being cleared by «prepClearRepCommit.sh» you must type
Beginning with release 2.0.0 gtgt automatically generates a specfile named «prj.spec». Using the command «rpm -bb prj.spec» you will get that rpm-package which contains the same files like the tarball generated with «make distcheck» and extracted and installed with the commands «configure --prefix=/usr/local && make && install»
For changing the spec-file see http://www.rpm.org/.
you can find more hints inside of the tarball.
Feel free to contact reincke@icdm.de or at karsten@fodina.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.fodina.de/karsten/ too.
It's a great pleasure for me to thank some people: