2.1 A step by step introduction

Here is described how to proceed, to create and compile a project based on the siliconBrain make environment.

2.1.1 Setup your package root directory

2.1.1.1 Create a package root directory

First thing you have to do is to create a directory, which will contain the complete sources and results of generated and compiled files for your package. The directory name automatically is your package name. So to start a new siliconBrain project “myProject” do a:

     cd directoryWhereYourProjectsdirShouldBeCreated
     mkdir myProject
     cd myProject

2.1.1.2 setup environment to use siliconBrain

To use siliconBrain it must be active in your environment. To that you have to execute:

     export siliconBrainPath=dirWhereSiliconBrainIsInstalled
     . $siliconBrainPath/setEnvironment

dirWhereSiliconBrainIsInstalled is where you installed siliconBrain. These two lines are also outputted after you have called siliconBrainInstall while being inside the siliconBrain distribution.

You can put this lines into your .bash_profile or in /etc/profile, if it should be available for all users on your system. You can also create a special xterm script, in which the environment is set. In that way you can selectively activate siliconBrain without polluting your standard environment.

2.1.1.3 create makefile

The only thing your makefile must contain is:

     include $(siliconBrainPath)/makefile

You can combine this step and the one before, if you just like to call siliconBrain features from within your makefile. Then you can leave your environment as it is and instead put two lines in your makefile:

     export siliconBrainPath=dirWhereSiliconBrainIsInstalled
     include $(siliconBrainPath)/makefile

2.1.1.4 create the frame of an empty project

Now that the root directory of your project is existing, you run make the first time. This will setup a directory tree and a couple of files, which should exist.

     cd myProject
     make

In your projects root directory you will have the following files:

     AUTHORS
     COPYING
     COPYING.DOC
     ChangeLog
     INSTALL
     INTRODUCTION
     NEWS
     README
     RELEASE
     TODO
     distribution
     documentation
     makefile
     siliconBrainInstall
     temporary

You will never edit these files except ChangeLog. The meaning of most of these files is described in README. distribution contains all things which are needed to use your package. siliconBrainInstall is a program (actually it is a bash script), which installs your package elsewhere. In documentation you will now have the following files:

     install.snippet.texinfo
     news.snippet.texinfo
     shortDescription.snippet.texinfo
     todo.snippet.texinfo
     introduction.snippet.texinfo
     readme.snippet.texinfo
     myProject.main.texinfo
     authors.snippet.texinfo
     longDescription.snippet.texinfo
     shortCopyingDoc.snippet.texinfo
     standardFiles.snippet.texinfo

Here myProject.main.texinfo is a frame where you put your main documentation in. For all the snippets, see DocumentationUsage.

2.1.2 The first documentationary steps

Some of the documents, which are created as frames for your writing, are used in a lot of places to generate files, docs, html, .... So you are not allowed to delete them. And some should have a reasonable contents.

shortDescription.snippet.texinfo

Put a one liner into here. This line will go into a lots of places.

introduction.snippet.texinfo

Here you put several pages of text to describe for a beginner, what your package is about.

myProject.main.texinfo

This will be your packages manual.

authors.snippet.texinfo

List the people who worked for this project.

longDescription.snippet.texinfo

Put a five liner here, to say what your package is.

2.1.3 A first program

In the projects root dir write your hello world program in a file named helloWorld.main.c. There after or before write a program called testMain, which calls your helloWorld. Normally it will be implemented in testMain.main.c or testMain.bash.

testMain is automatically called by the makefile if it exists. Now you can compile and run your program by just entering make.

2.1.4 Create a web version of your sources

make web