Copyright (C) 2003, 2004 Joerg Kunze

   Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.1 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
Texts.

siliconBrain is a generic `make' environment. The idea is that the user
does not necessarily know something about `make'. Instead he creates
just a reference to siliconBrain's `makefile' and then everything works
auto-magically and generic.

   The first time the user calls `make' in her project root directory,
a lot of things are generated, to be used as a frame for development:

   * A standard directory tree, containing `documentation' to hold all
     written documents, a `distribution' to hold all files and programs
     needed when using the new package, a `temporary' to hold really
     temporary things.

   * A couple of Texinfo documents as the starting point of the
     siliconBrain's users own documentation.

   * Some _capital_ files like `README', `COPYING' and others, which
     are automatically generated out of the Texinfo files.


   Open source projects or packages are the only, which siliconBrain
really supports. So are GNU's GPL and FDL automatically copied into the
projects root directory. When installing a siliconBrain based package
sources are included. When publishing the documents onto a web, the
htmlilized sources are included almost all pages contain GPL or FDL
hints.

   siliconBrain is mainly based on Linux and a lot of programs from the
GNU project (and TeX). The main components are gcc, GNU make, Texinfo,
bash, gawk. I do not plan to port this software to other platforms
(except eventually HURD). Projects done with siliconBrain are not
easily ported as well. I use the full features of GNU, TeX and Linux. I
have never tried, but probably it is relatively easy to port to a
GNU/OTHEROS system.

   To use siliconBrain as development environment forces the programmer
to observe certain standards. These are for example:

   * All documents are written with Texinfo.

   * All documents are put into `documentation'.

   * Bash programs end with `.bash', Gawk scripts with `.awk'.

   * C-programs, which should be linked to main's must have the
     extension `.main.c'. Those, which should go into a library
     `.lib.c'.

   siliconBrain implements a lot of philosophical principles, of which
the most important are:
   * "paradigm of total automation": do _nothing_ manual.

   * "redundancy is Satan": nothing, really nothing should be doubled.
     No piece of information should be implemented twice.

   * "quality is velocity of change": That is how quick an error can be
     corrected and how quick new features can be implemented.

   * "the "invent a new OS" anti pattern": Never implement something,
     which an operating system has already implemented. For example, do
     not write a memory management. This is against j2ee.

   * "compile time decisions are always better than run time
     decisions": Everything, which is now during compile-time should be
     decided when building the package. This is against java.


   The following goals are already reached:

   * No need to setup a makefile before starting a new project. Just
     have the following two lines in the projects `makefile', and
     everything is build generically:

          export siliconBrainPath := $(HOME)/sandbox/siliconBrain/distribution
          include $(siliconBrainPath)/makefile

   * A standard directory tree is automatically created:

          ./distribution
          ./distribution/programs
          ./distribution/documentation
          ./distribution/documentation/web
          ./distribution/documentation/web/index
          ./distribution/documentation/web/sourceTree
          ./distribution/documentation/web/info
          ./distribution/documentation/man1
          ./distribution/data
          ./distribution/data/documentation
          ./distribution/include
          ./temporary
          ./documentation

   * Templates for documentation are created:

   * Capital files are created out of Texinfo documentation and GNU
     licenses are copied into a project.:
          AUTHORS
          COPYING
          COPYING.DOC
          INSTALL
          INTRODUCTION
          NEWS
          README
          RELEASE
          TODO

   * Use long names instead of abbreviations. So executables are in
     `programs' not `bin'.

   * Shell scripts have `.bash' as extension in source directory and no
     extension in the `programs' directory.

   * Use two level extension like `.lib.c' to know what to do with a c
     source. `.lib.c' goes into a lib, `.main.c' is linked to an
     executable.

   * Automatically create a html version for the source directory.

   * Automatically put release, cvs and save version information into
     all sources.

   * `make public' automatically increases the release number, writes a
     cvs tag creates a `.tar.gz' and copies this and the generated html
     sources to a web host.

   * Automatic installation procedure.

   * Use a package without installing it into common directories, and
     so be able to not use a package or to use different versions of a
     package on the same computer.

   * It is possible to run a package without installing it at all.

   * Use `test' as the default target. And test siliconBrains
     `makefile' automatically.

   * Generate handling of options, H-file, man description and info page
     out of a command specification avoiding a lot of redundancies.

   * Use c as the language for specifications. So specifications are
     compiled and linked. At the end we have something like a
     "executable specification".

   * First version of a record (data structure) specification, which
     then is automatically transformed into a command (record command).

   * Configurations are executable xml producing files.

   * Configuration parameters and options are one and the same.

   * Options can be specified on command line, via environment variables
     or via configuration programs.

   * Do not have xml sources, but xml producing programs. Use a special
     xml printing library to guarantee pretty printed xml and to allow
     avoiding redundancies.

   * Configurations are not stored into the packages installation
     directory. So it is save, just to `rm -Rf' the package without
     loosing configuration information.

   * Several users can use a package with different configurations on
     the same computer.

   * The same user can use a package with different configurations on
     the same computer.

   * publish, download and install is tested automatically.

   * Executable configurations can be implemented in any language.

   * Try to give c scripting capabilities (just the very beginning), by
     using siliconBrainLib (../../siliconBrainLib/index.html)