$Header: /CVSROOT/tinolib/old/README,v 1.4 2007-09-17 17:45:09 tino Exp $

----------------------------------------------------------------------

tinolib was designed to be C89 and POSIX compliant.  However more and
more C99 features will be utilized, but these features shall be kept
optional if possible.  If you find something which is not in
compliance you probably found a bug or something I am not aware of.
In this case, please inform me <webmaster@scylla-charybdis.com> (but
beware, I am over-spammed).

To be C89 compliant with long names tinolib has internal linkage.
Therefor it is based on includes and nearly everything is kept static.
A normal program with tinolib is one single file which is pulled
together through the C-Preprocessor.  However Makefile.tino knows a
little bit about dependencies, too, such that you can compile and link
serveral object files, too.  But in this case you often loose C89
compatibility as the link might work on your system but not somewhere
else (routine1 and routine2 unter C89 both define the object ROUTIN).

tinolib shall be modular and optional.  That is, you do not need all
the contents.  However currently a proper helper is missing to make
programs independently of tinolib.  Note that developing/using tinolib
needs a huge environment while compiling the result (after make dist)
shall work on all minimal environments.

When it comes to additional external resources which need downloads,
configure, automake you probably need a full Linux environment (like
CygWin).

----------------------------------------------------------------------

Naming convention:

I now start to change the lib to comply to C99 for external names,
that is a NEW NAMEING CONVENTION for names up to 31 characters.

- tino_module_function_args schema is retained, however function names
  must not exceed 25 characters this way.

- functionA()	Automatic internal error handling (via tino_err).
- functionE()	Error: returns errors but EINTR handled internally
- functionI()	Interruptable: As before, but returns on EINTR
- functionO()	always OK Routine, cannot fail (like returning void)
- functionN()	always OK Routine, but can return NULL or negative
- functionU()	Usage not recommended: No more use this one!
- function()	Old version, unspecified, deprecated

Also after the capitalized letter there can be lower case letters for:
- functionXb()	Bad sideffects
- functionXn()	Non threadsafe or non reentrant
- functionXp()	Printf() style arguments
- functionXs()	Sideffect warning
Multiple lowercase letters are sorted ABC.

- Type s functions shall not be called more than once at a time, as
  they might return internal static buffers.

- Type p functions take %v as a varargs parameter.  This option has no
  sideffect on varargs parameter.  That's why a v type can be missing.

In case you wonder: Tinolib isn't fixed, so such a rename is possible.
I think, this naming convention will hold in future, but tinolib is
not a set of fixed work like a standard library which upholds some old
compatibility just to be compatible.  It is thought to make life
easier.  So from time to time you might need to rename functions or
change some things you conform to a standard way which previously
needed manual crafting.  This also is why tinolib is always part of
all distributions and not independent of it.  Also I need not to obey
to this convention for any reason.

------------------------------------------------------------------------

You have following:
- Linux
- A copy of tinolib at /path/to/library/tino/
- A source file !NAME!.c or !NAME!.cc
  where !NAME! is `basename "$PWD"`
- Now to start from fresh, just do:
	/path/to/library/tino/setuptino.sh
  this will create the initial Makefile.
- To change the parameters etc. just do
	vi Makefile.tino
- If you need to recreate the Makefile, just do
	make -f Makefile.tino
  However, most times the Makefile will update itself from
  Makefile.tino automagically.
- It's quirky, sometimes make must be called several times until
  things settle.  If not, don't panic, the first `make` was ok!

Note that the basic functions of the Makefile then can live without
the subdirectory tino/ - some errors will show up, but everything
still compiles.

----------------------------------------------------------------------

What's the dark matter with all this here?

I want a hassle free method of keeping everything updated for me.  I
want "make" to make it all, so no "./configure; make".  "make" must be
enough, as "make" already is insane (ask non-programmers how to
compile software, they will not tell you "to use make", so "make" is
insane and "configure" is even more insane).  I want to be able to
build everything without GNU extensions.  This does not mean to not
use GNU extensions at all.  However it shall be easy to comment them
out and still have a successful build.  I want it easy.

Additionally a minimum of standard unix utilities shall be needed to
run this all.  Note that I already think it needs too many of them.
However "make all" shall still do, I hope.

A third thing is, to be able to concentrate on the source, not on
incompatibilities.  So the library shall handle it all.  And moreover
it shall conform to the C89 standard, such that you can expect that
you are able to compile on any system for which the source is anyhow
meaningful.

----------------------------------------------------------------------

Prerequisites for "make all" in a distribution currently is:

1) make  (not neccessarily GNU make)
2) gawk  (you need GNU awk, sorry)
3) touch (could not circumvent this, sorry)
4a) An C89 compliant ANSI-C compiler which make knows about.
4b) Dito an ANSI-CC compiler, in case of C++
5) The proper set of includes and libraries (possibly all GNU).

Nothing else (not even a bash, perl etc.) shall be needed,
and not a compiler with support for -M or -MM.

----------------------------------------------------------------------

At least, that's the idea behind it, even that I think I failed
completely.  However the basic needs are relatively moderate.

My long term goal for this here is (not joking): All you need is a
suitable ANSI-C compiler with libraries and such to compile my
distributions.  For this there perhaps will be a little
Makefile.tino.run.c which can be compiled to a program which calls the
compiler for you (if you find a way to even get rid of the compiler, I
would be glad.  Well, ok, that was a joke now *eg*).

However, to use all features of tinolib, you probably need a huge
Linux environment and some undefined and unclear setups (like CVS) in
place.  But still it's the idea for the distribution to have an easy
"make all" process.  And that the distribution can be independent of
tinolib if the sources do not depend on this library.

All portability issues shall be handled in tinolib in future, such
that you do not need a single #if in your source except for compile
time features.  You get the idea, that's what I want.

Well, I'm far away from my goal, but it's evolving in slow motion.

$Log: README,v $
Revision 1.4  2007-09-17 17:45:09  tino
Internal overhaul, many function names corrected.  Also see ChangeLog

Revision 1.3  2007/05/08 03:14:04  tino
Current information about future naming convention

Revision 1.2  2006/10/03 20:26:52  tino
Ubuntu has no gawk as awk, so gawk used instead of awk

Revision 1.1  2006/01/29 17:49:52  tino
Improved documentation and "make test"

