Java4c - User contributions [en]

Bazaar-Notes

Admin — Fri, 09 Sep 2011 08:25:36 GMT

Admin: /* More as one Repository for one product */

@ident=Bazaar_notes

Links:
* [[Bazaar-guide]]: a guide to use Bazaar.

This size is in german, because it is discussed in a german team. It will be presented in english in the future. TODO

==Kurzer Abriss, Arbeit mit MKSSI, git, mercurial, Bazaar==

Hartmut: MKSSI ist seit über 10 Jahren bei mir in Gebrauch.
* Nur auf Arbeit, zentrale Administration,
* Die MKSSI-Software wird normalerweise nicht ständig updated. Das Arbeiten ist nicht sehr schnell, eher etwas für ordentliche Pflege.
* Wird gemacht, für die Versionen, die herausgegeben werden. Nicht für stündliche kleine Änderungen. Da wäre der Arbeitsaufwand zu hoch.

Hartmut: git war das erste der 'dritten Generation' für mich.
* Geht ganz gut, init commit, alles ganz einfach
* Nachschauen der Änderungen: Hier ist die GUI (gitk) nicht sehr bedienerfreundlich. Die schnelle Tastaturbedienung ist mangelhaft, der Tastaturfokus ist im falschen Teilfenster. Immer mit Maus schieben ...
* Linux-like cmdline-Bedienung auf Windows-PC ist für mich eher interessant.

Hartmut: mercurial - ähnlich wie git, nur eher für windows, eigentlich sehr ähnlich git.

Hartmut: Bazaar gefällt mir persönlich wegen der GUI besser.

Hartmut: Alle drei Systeme sind aber funktionell eher ähnlich. Ich pflege Quellen in Bazaar, um sie dann auch in hg zu committen, mit selbigem commit-Text wie in Bazaar zuvor zusammengestellt. Das ist nur ein Aufruf. Ein Hg-Archiv beispielsweise für CRuntimeJavalike liegt auf [[https://bitbucket.org/jchartmut/cruntimejavalike bitbucket.org/jchartmut/cruntimejavalike]]. Hg deshalb, weil die bitbucket-Seite nur hg unterstützt. Der Aufwand, in hg doppelt zu pflegen, ist kaum erhebenswert.

;Commit-Text zusammenstellen

:Vorderhand geht es beim Commit-text darum: Was leistet diese Version insgesamt, unterschied zur Vorversion. In der Zweiten Linie geht es aber um die Änderung in den einzelnen Files.

:Sind im Commit sehr viele Files enthalten, dann handelt es sich meist um das Ergebnis eines Refactoring wegen einer Änderung. Solche Änderungen brauchen in den Quellfiles nicht vermerkt werden, zuviel Aufwand, uninteressant.

:Sind dagegen wenige Files geändert, dann lag meist auch eine Änderung der Funktionalität vor. Diese sollte unabhängig vom Commit in den Quellfiles notiert werden. Hier hilft aber die Differenzanzeige, um während des Commit die Änderungen in den Files zu vermerken. Man kann einen passenden Commit-Text zusammenstellen, dabei die Änderung der Einzelfiles betrachten und dabei in den Einzelfiles Änderungen notieren (log des Files).

:Ein automatisches Eintragen der Änderung in den Files aus dem checkin-Textes aus der Arbeit mit dem Source-Integrity-System produziert meist Einträge in den Files, die die Änderungen schlecht abbilden. Das liegt daran, weil der Arbeitsaufwand für jeden Einzelfile zu hoch ist. Dieses automatische Eintragen ist aber eine häufig verwendete oder voreingestellte Methode bei MKSSI & co.

: Der Arbeitsaufwand bei manuellem Eintragen in den File ist deshalb bei Bazaar geringer, weil
:* Es gibt eine schnelle Übersicht, welche Files betroffen sind. Einfacher Knopfdruck für Viewdiff. Man kann schnell auswählen, bei welchen Files ggf. gleiche Einträge überhaupt notwendig sind. Nicht bei allen geänderten.
:* Mit den Files, die keine wesentlichen Änderungen enthalten sondern nur Anpassungen an Änderungen anderer Files, braucht man sich also gar nicht beschäftigen.
:* Die Änderung im File eingetragen und per Zwischenablage auch im Commit-Text abgelegt ist dann eigentlich nur einmaliger Aufwand, nicht zweimal.
:* Wenn es wesentliche Änderungen sind, dann ist die Beschreibung der Änderung auch ein schöpferischer und nicht formeller Akt. Dann lohnt es sich auch, die entsprechend notwendige Zeit aufzubringen. Möglicherweise wird man bei der Änderungsbeschreibung im File auch noch weitere dabei entdeckte Pflegekorrekturen anbringen, die insgesamt die Quelle weiter aufwerten. Dann hat es sich sowieso gelohnt.

==Source Content Management oder hart archivieren? Nur Quellen im SCM?==

Eine harte Archivierung ist das Verpacken der Files auf einem Datenträger. Da das Zip-format sich als langjährig beständig erwiesen hat, kann man ganze File-Bäume zippen und irgendwo aufheben.

Nachteil: Keine Unterstützung für Diff-View außer auspacken und mit einem Diff-tool vergleichen. Der Total-Commander eignet sich dazu allerdings recht gut, da er in beiden Paneelen in zip-Archive tief eintauchen kann.

Vorteil: Unabhängig von einem Tool, die Files einer Version sind zusammengebunden einfach da. Es hat sich schon oft als günstig erwiesen, lange Jahre zurückliegende Files nicht mit den damaligen Tools aufrollen zu müssen sondern einfach entzippen.

Der Vorteil für die Langjährigkeit sollte bedacht werden.

=>Schlussfolgerung: Ab und zu zippen und wegpacken, mindestens bei wichtigen Releaseständen. Aber unnütze zipfiles auch mal löschen.

=>Schlussfolgerung: Für akutelle Softwareentwicklung jedenfalls ein Source-Integrity-Tool nutzen, Zippen nur zusätzlich.

===Verzeichnissstuktur-Rückschluss===

Sowohl für das Zippen als auch für Sourcenpflege, Sourcenaustausch usw. liegt der tatsächliche Umfang von Sources insgesamt meist in einem Bereich von wenigen Megabyte. Damit ist der Datenaustausch mindestens erleichtert. Wenn man in die selbe Verzeichnisstruktur in der Quellen liegen noch hineintue:
* Objects
* erzeugte executable und umfangreiche Datenbasis-Files (Visual Studio ncb-Files und dergleichen)
* logfiles, Output-Files beim Testen
* alte Archive (zips)

dann springt der Umfang des Verzeichnisbausms von wenigen Megabyte ganz schnell auf -zig Megabyte. Das Problem merkt man
* beim zippen (ganz schnell mal ablegen zum späteren Vergleich)
* beim Vergleichen (alle Obj erscheinen als geändert, alles rot, erst mal schaun was das ist)
* bei der Pflege der Sources in einem SM-system (Source Management): viele nicht erfasste files: Sind die wichtig? Ach, sind nur Obj, doch ein wichtige wird übersehen.

=>Schlussfolgerung: Möglichst Sources von Testfiles und Executables trennen. Die wenigen Files, die nicht trennbar sind (weil die Tools sie ins aktuelle Verzeichnis legen), in einer ignore-Liste erfassen, ggf. beim zippen ausschließen usw. Sind es wenige, dann sind sie verwaltbar
* Object-Files auf einem tmp-Ordner speichern
* Generierergebnisse neben dem Source-Baum speichern.

===Archivieren von Executables===
Aus oben genannten Gründen sollten die Libs und Executables ''nicht'' mit den Sources im SM gemischt werden.
* Die libs und executables könnten einerseits immer aus den Sources generiert werden (wenn alles richtig ist)
* Die libs und executables sind nicht vergleichbar mit üblichen diffs.
* Die libs und executables sind im Code-Umfang zu hoch.

Es ist aber wichtig, libs und exe im Zusammenhang mit einem Checkpoint der Sources zu speichern.
* Als Auslieferungsstand
* Als wichtigen Teststand für Rückrüsten, möglicherweise ein Kandidat für Auslieferung.

Lösung:
* Beim committen eines guten Standes, der angetestet ist, ein kleines batch laufen lassen, das die exes lokal kopiert mit Datumskennzeichnung.
* Damit sind mehrere exes mit Datumsverbindung zum commit lokal vorhanden. Es kann getestet werden.
* '''Auslieferung: Executables und ggf. libs als zip abspeichern''',, siehe oben. Dabei auf den Stand zugreifen, der vorher lokal kopiert wurde und garantiert aus den Sources, die committed wurden, erstellt wurde.
* Nur bei '''Master-Releases''', die entgültig ausgeliefert werden, sollte folgeder Aufwand getrieben werden: Nach erfolgreichem Test die Quellen auf Produktgenerierungsrechner von anderer Person auschecken, neu compilieren, neues Generat erstellen und nochmals testen. Diese Vorgehensweise sichert die Konsistenz der Quellen mit dem Generat und dürfte bei Auslieferungen wichtig sein, dauert aber in der täglichen Fortschrittsarbeit einfach zu lange.

==More as one Repository for one product==
@ident=multiBzr

;Products with more as one components.

:Products are build with more as one components. Any component should be independent from the concretely product, tested as 'component' and may be used in more as one product.

:Conclusion: Do not mix sources, separate it. Therefore any component needs its own bzr archive.

;Sources of components should be located in a subdirectory of the product source tree. It is helpfull to use sub-directories to keep tidiness.

:In linux the sub directory may be a symbolic link. It means, the sources are located anywhere other in the file tree really and they can be maintained outside of the products source tree. In windows a real copy is necessary. But note, that a tool can often gotten the sources from any pathes in the file tree. It is a problem of absolute pathes versus a local sandbox.

:Conclusion: The .bzr repositiory of a component should be located in a sub directory of the product source tree.

:The name of the sub directory should, but doesn't need be identical with the name of the component.

;Getting of source tree of a component, getting its bzr archive

To get the bzr repository for a component of a product, use a simple batch or script file inside the product file tree in that directory, where the components root directory should be stored.

srcJava_Zbnf/ ..... This is the components directory, where its srcJava_Zbnf/.bzr should be located.
getBzr_srcJava_Zbnf.bat ..... This is the batch file to get the bzr archive of the component.

The batch file contains the simple line:

bzrGetVersion srcJava_Zbnf 59

This line should be kept simple and independent of any operation system. Note, that the batchfile works under linux too, if it is set 'executable'. The batchfile calls another script, 'bzrGetVersion' and names the storing directory and the requested version.

The '''bzrGetVersion''' scriptfile should be located anywhere in the PATH of the computer. It is a thing of installation, not a thing of the designated sources of the concrete product. It contains - for windows - and should be adapted to the concretely conditions at the PC-installation:

@echo off
REM How to get a component's sources:
REM The sources are contained in an bzr archive.
REM The bzr archive is an distributed repository.
REM An archive can exist as a copy on several places,
REM for example at a external hard disk or in network or as a local copy in another drive.
::
REM This is the path to all archives for this computer, correct it if necessary:
set BZR_ARCHIVEPATH=D:/Bzr
::
REM The batch renames the current directory if it is existing yet:
if not exist %1 goto :noCurrent
if exist %1.old rmdir /S/Q %1.old
if exist %1.old goto :nodelOld
ren %1 %1.old
if exist %1 goto :noRename
:noCurrent
::
REM copy the bzr archive and resynchronize all members with the required revision
echo on
bzr checkout %BZR_ARCHIVEPATH%/%1 %1 -r %2
@echo off
if not exist %1 goto :noBzr
goto :ende
::
:noRename
echo can't rename %1 to %1.old. It may be used yet. Do it manually!
pause
goto :ende
::
:nodelOld
echo can't delete %1.old. It may be used yet. Do it manually!
pause
goto :ende
::
:noBzr
echo The bzr archive is not pulled. The version may be faulty or the source path of bzr does not exist.
echo See error messages above.
pause
:ende
exit /B

If you follow the command statements, you can see that an existing directory is kept, of found, but the directory of the component is get newly anytime. It assumes that all bzr archives are located in one directory in the file tree, which can be an external disk too or an network path. See 'BZR_ARCHIVEPATH'.

The content of the archive will be cloned with the 'bzr checkout' command. The files are resynchronzed therefore. An independent working with the files and the cloned archive is possible, if necessary. The working can be pushed to its parent later using 'bzr push', 'bzr merge' etc. But in most cases only the resynchronized version of files are need.

==Mehrere Produkte aus einem Repository==
Das große Thema ist Wiederverwendung (Reuse). Häufig zu Beobachten: Reuse besteht aus copy'n paste and change. Die Quellen wandern also irgendwo anders hin, bzgl SCM auch für den einzelnen besser zu beherrschen - man muss sich nur mit dem beschäftigen, was man selbst hat.

Das ist keine wirkliche Wiederverwendung. Der wirkliche Vorteil des reuse geht dabei verloren:
* Fehler, die in Produkten festgestellt werden, werden in den jeweiligen Modulen korrigiert und sind dann automatisch auch für andere Produkte mit korrigiert, obwohl sie dort ggf. noch gar nicht aufgefallen sind.

Für true-reuse ist es notwendig, die Software-Module so zu bauen, dass sie '''unverändert''' in verschiedenen Produkten verwendbar sind und das Änderungen für alle Produkte nutzbar sind. Das ist eine Frage der Schnittstellen. Die Schnittstellen sind viel wichtiger als die innere Funktionalität. Letztere kann man immer noch verbessern. Schnittstellenänderungen sind kritisch. - Andererseits sind Schnittstellenänderungen auch verträglich, wenn sie formell adaptiert werden können.

Ein shared-Repository in bazaar scheint die Lösung zu bieten, aus einem recht großen Quellenumfang für verschiedene Komponenten verschiedene Quellen herauslösen zu können. Die Komponenten haben selbe gemeinsame Quellen, ggf. in verschiedenen Revisionen, die aber immer abgeglichen werden können sollten. Die Komponenten sind dann Basis für ein Produkt. Komponenten existieren in Form von libs oder jars in Java und können eigenständig getestet werden:

Quellen Komponenten Produkte
viele ===> weniger ===> aus Komponenten
verschiedene überschaubar und Produkt-spezial-Quellen
gebaut.

Wie funktioniert shared-Repository als zentraler Bezug - bin beim testen. (Hartmut)
==Zentrale Ablage für Repositories==
@ident=centralRepos

Man kann immer und überall Repositories haben. Behält man den überblick und synchronisiert diese gegenseitig (push, pull), dann gibt es auch nicht zuviele Seitenzweige.

Jedoch, arbeiten viele Leute mit den Repositories, auch weniger eingeweihte, einfache Nutzer, anderes Problem Archivierung, langjähriges aufheben: Dann sollte an einer definierten Stelle das Master-Repository stehen. Jeder Quellenbearbeiter hat die Pflicht, sich mit dem Master-Repository abzustimmen, also seine Änderungen zu pushen oder von dort zu pullen. Gegebenenfalls sollte eine Person mit der Pflege des Master-Repositories beauftragt sein. Mindestens bei Releaseständen muss diese Person dort bereinigend eingreifen.

===Creating one shared repository in the local space===
The ''local space'' means any external hard disk, network folder or such which is owned by one person, by me. It is my local space, which can be used from some more people in my direct environment.

For any component of sources one shared repository should be created one time. On one sub directory per component: ''bzre: Bazaar -> Start -> Initialize: (x) Shared repository''. An existing plain branch can be pushed to them.

===Creating a branch for working===

* Create a new plain branch at the working position: ''bzre: Bazaar -> Start -> Initialize: (x) Plain branch''.
* Pull from a shared repositiory: ''Button Pull, select the shared repository, select a branch.
** If there are some files already, create the branch at a new position and then move .bzr subdir.

==Branches und dessen Auflösung==
@ident=.branch

;Viele Seitenzweige wegen unterschiedlichen Korrekturen

:Man kann sich auf den Standpunkt stellen, bei Korrekturen für kundenrelevante Software jeweils nur das aufgetretene Fehlerbild zu behandeln, alle anderen Softwareteile unverändert zu lassen. (''Do not touch a running system''). Das ist eine weit verbreitete Vorgehensweise. Folge sind dann sehr viele Seitezweige, die kaum mehr zusammenfließen.

: Primär ist diese Vorgehensweise richtig.

: Es zeigt sich aber, dass eine Änderung in Quellen, auch Restrukturierung, häufig zwar Nacharbeiten erforderlich macht. Diese Nacharbeiten sind aber formal abhandelbar. Man braucht nicht an jeder Stelle einer notwendigen Adaption an geänderte Quellenstände nachzudenken sondern muss nur den Compiler befragen. Kommt keine Fehlermeldung, ist alles in Ordnung. Eine Fehlermeldung soll mit formellen anschauen von Aufrufargumenttypen usw. behebbar sein, ohne dass man in die eigentliche Funktionalität einsteigt. Ist eine solche Nacharbeit möglich, dann kostet diese nur die Zeit der Pflege der Quellen, keine extra Testzeit. Zudem kann die Quellenpflege von jemanden ausgeführt werden, der zwar sehr gute Kenntnisse von Quellen und COmpiler hat, aber keine Tiefenkenntnis für die jeweilige Anwendung haben braucht. Man kann also delegieren.

: In diesem Sinn ist eine Adaption eines Produktes an veränderte Quellen der Komponenten möglich und zweckmäßig. Mann kann dann eher an einem Hauptzweig arbeiten.

: Schlussfolgerung: Schnelle Änderungen ->Seitenzweig, Auflösen dessen, Änderung in Hauptzweig einfließen lassen und Adaption des Produktes auf Hautpzweig der Komponenten ausführen.

===Side branches===
less experience

bzr checkout ../masterlocation . -r REVNR

Gets a part of trunk untio REVNR. It is similar

bzr revert -r REVNR

What is the difference???

bzr update ../masterlocation .

This copies all files in the current dir. It seems to destroy the older-revision side branch (?)

Is there a possibility to checkin changes based on a older revision, without any merge. Only the changed files based on the older revision should be stored in the bazaar repositiory - to compare with other versions or look for changes later. Background: Changing of some source files to bugfix an older software. The reason is not develop and merge.

The workflow of develop and bugfix in a decentralized team is explained in
* [[http://doc.bazaar.canonical.com/latest/en/user-guide/organizing_branches.html doc.bazaar.canonical.com/latest/en/user-guide/organizing_branches]].

But this is not the problem of side branches, more the problem of development in team.

'''An side glance to git''':

$ git branch bugfix

creates a branch named 'bugfix' in the same only one repository. It is a branch with the same revision as the current one.

$ git checkout bugfix
now switches to the named branch.

$ git reset -q COMMITNR

This moves the current revision of the current branch (it is 'bugfix' to a older revision. COMMITNR is the hash number of any commit, see git log

$ git checkout .

resynchronized all files of the selected revision.

...changing any files and

$ git commit

builds a side branch in the repository (archive).

Now a switch to another branch and its revision is possible in the same sandbox to work with it:

$ git checkout master

now switches back to this named branch and resynchronizes all files. Work with it, commit etc.

If there should be worked only at one side branch to any time, and be worked at another side branch to another time, then only one sandbox is necessary. You can switch between the branches. The files are changed, all files are stored in the git archive.

If there should be worked with more as one side branches to the same time, a copy of the git archive is necessary. The archive and the files should be stored at different places on the hard disk, or at more as one computer etc. It isn't recommended to use the same git archive, may be with an symbolic link in linux. The disadvantage is: The git archive knows the current branch, which was selected with 'checkout'. If you want to use only one archive but more as one sandbox for the files, you can have a symbolic link in the sandboxes to the same archive. But then you have to switch between the side-branches before any status, commit etc. action are done in one of the sandboxes. But be attentive to your files. You may overwrite they if you are careless. You can't do that at the same time, maybe more as one people in network. It will be confused if they are work concurrently.

I haven't test yet, but it shouldn't a problem to merge the more as one git archives without conflicts, if only one archive has changed only one side branch.

[[http://www.vishia.org/SwEng/pictures/git-side-branch-example.jpg Image: example side branches in git]]

'''Now back to bazaar''':

John A Meinel proposed the following answer:

If you want to commit new changes based on an older revision, you generally want to start a new branch. So something like

bzr branch master feature -r OLD
cd feature
bzr commit

If you are using a checkout you can do

cd checkout
bzr branch --switch -r OLD ../master ../feature

TODO test

Bazaar-Notes

Admin — Fri, 09 Sep 2011 08:22:47 GMT

Admin: /* Mehrere Repositories für ein Produkt */

@ident=Bazaar_notes

Links:
* [[Bazaar-guide]]: a guide to use Bazaar.

This size is in german, because it is discussed in a german team. It will be presented in english in the future. TODO

==Kurzer Abriss, Arbeit mit MKSSI, git, mercurial, Bazaar==

Hartmut: MKSSI ist seit über 10 Jahren bei mir in Gebrauch.
* Nur auf Arbeit, zentrale Administration,
* Die MKSSI-Software wird normalerweise nicht ständig updated. Das Arbeiten ist nicht sehr schnell, eher etwas für ordentliche Pflege.
* Wird gemacht, für die Versionen, die herausgegeben werden. Nicht für stündliche kleine Änderungen. Da wäre der Arbeitsaufwand zu hoch.

Hartmut: git war das erste der 'dritten Generation' für mich.
* Geht ganz gut, init commit, alles ganz einfach
* Nachschauen der Änderungen: Hier ist die GUI (gitk) nicht sehr bedienerfreundlich. Die schnelle Tastaturbedienung ist mangelhaft, der Tastaturfokus ist im falschen Teilfenster. Immer mit Maus schieben ...
* Linux-like cmdline-Bedienung auf Windows-PC ist für mich eher interessant.

Hartmut: mercurial - ähnlich wie git, nur eher für windows, eigentlich sehr ähnlich git.

Hartmut: Bazaar gefällt mir persönlich wegen der GUI besser.

Hartmut: Alle drei Systeme sind aber funktionell eher ähnlich. Ich pflege Quellen in Bazaar, um sie dann auch in hg zu committen, mit selbigem commit-Text wie in Bazaar zuvor zusammengestellt. Das ist nur ein Aufruf. Ein Hg-Archiv beispielsweise für CRuntimeJavalike liegt auf [[https://bitbucket.org/jchartmut/cruntimejavalike bitbucket.org/jchartmut/cruntimejavalike]]. Hg deshalb, weil die bitbucket-Seite nur hg unterstützt. Der Aufwand, in hg doppelt zu pflegen, ist kaum erhebenswert.

;Commit-Text zusammenstellen

:Vorderhand geht es beim Commit-text darum: Was leistet diese Version insgesamt, unterschied zur Vorversion. In der Zweiten Linie geht es aber um die Änderung in den einzelnen Files.

:Sind im Commit sehr viele Files enthalten, dann handelt es sich meist um das Ergebnis eines Refactoring wegen einer Änderung. Solche Änderungen brauchen in den Quellfiles nicht vermerkt werden, zuviel Aufwand, uninteressant.

:Sind dagegen wenige Files geändert, dann lag meist auch eine Änderung der Funktionalität vor. Diese sollte unabhängig vom Commit in den Quellfiles notiert werden. Hier hilft aber die Differenzanzeige, um während des Commit die Änderungen in den Files zu vermerken. Man kann einen passenden Commit-Text zusammenstellen, dabei die Änderung der Einzelfiles betrachten und dabei in den Einzelfiles Änderungen notieren (log des Files).

:Ein automatisches Eintragen der Änderung in den Files aus dem checkin-Textes aus der Arbeit mit dem Source-Integrity-System produziert meist Einträge in den Files, die die Änderungen schlecht abbilden. Das liegt daran, weil der Arbeitsaufwand für jeden Einzelfile zu hoch ist. Dieses automatische Eintragen ist aber eine häufig verwendete oder voreingestellte Methode bei MKSSI & co.

: Der Arbeitsaufwand bei manuellem Eintragen in den File ist deshalb bei Bazaar geringer, weil
:* Es gibt eine schnelle Übersicht, welche Files betroffen sind. Einfacher Knopfdruck für Viewdiff. Man kann schnell auswählen, bei welchen Files ggf. gleiche Einträge überhaupt notwendig sind. Nicht bei allen geänderten.
:* Mit den Files, die keine wesentlichen Änderungen enthalten sondern nur Anpassungen an Änderungen anderer Files, braucht man sich also gar nicht beschäftigen.
:* Die Änderung im File eingetragen und per Zwischenablage auch im Commit-Text abgelegt ist dann eigentlich nur einmaliger Aufwand, nicht zweimal.
:* Wenn es wesentliche Änderungen sind, dann ist die Beschreibung der Änderung auch ein schöpferischer und nicht formeller Akt. Dann lohnt es sich auch, die entsprechend notwendige Zeit aufzubringen. Möglicherweise wird man bei der Änderungsbeschreibung im File auch noch weitere dabei entdeckte Pflegekorrekturen anbringen, die insgesamt die Quelle weiter aufwerten. Dann hat es sich sowieso gelohnt.

==Source Content Management oder hart archivieren? Nur Quellen im SCM?==

Eine harte Archivierung ist das Verpacken der Files auf einem Datenträger. Da das Zip-format sich als langjährig beständig erwiesen hat, kann man ganze File-Bäume zippen und irgendwo aufheben.

Nachteil: Keine Unterstützung für Diff-View außer auspacken und mit einem Diff-tool vergleichen. Der Total-Commander eignet sich dazu allerdings recht gut, da er in beiden Paneelen in zip-Archive tief eintauchen kann.

Vorteil: Unabhängig von einem Tool, die Files einer Version sind zusammengebunden einfach da. Es hat sich schon oft als günstig erwiesen, lange Jahre zurückliegende Files nicht mit den damaligen Tools aufrollen zu müssen sondern einfach entzippen.

Der Vorteil für die Langjährigkeit sollte bedacht werden.

=>Schlussfolgerung: Ab und zu zippen und wegpacken, mindestens bei wichtigen Releaseständen. Aber unnütze zipfiles auch mal löschen.

=>Schlussfolgerung: Für akutelle Softwareentwicklung jedenfalls ein Source-Integrity-Tool nutzen, Zippen nur zusätzlich.

===Verzeichnissstuktur-Rückschluss===

Sowohl für das Zippen als auch für Sourcenpflege, Sourcenaustausch usw. liegt der tatsächliche Umfang von Sources insgesamt meist in einem Bereich von wenigen Megabyte. Damit ist der Datenaustausch mindestens erleichtert. Wenn man in die selbe Verzeichnisstruktur in der Quellen liegen noch hineintue:
* Objects
* erzeugte executable und umfangreiche Datenbasis-Files (Visual Studio ncb-Files und dergleichen)
* logfiles, Output-Files beim Testen
* alte Archive (zips)

dann springt der Umfang des Verzeichnisbausms von wenigen Megabyte ganz schnell auf -zig Megabyte. Das Problem merkt man
* beim zippen (ganz schnell mal ablegen zum späteren Vergleich)
* beim Vergleichen (alle Obj erscheinen als geändert, alles rot, erst mal schaun was das ist)
* bei der Pflege der Sources in einem SM-system (Source Management): viele nicht erfasste files: Sind die wichtig? Ach, sind nur Obj, doch ein wichtige wird übersehen.

=>Schlussfolgerung: Möglichst Sources von Testfiles und Executables trennen. Die wenigen Files, die nicht trennbar sind (weil die Tools sie ins aktuelle Verzeichnis legen), in einer ignore-Liste erfassen, ggf. beim zippen ausschließen usw. Sind es wenige, dann sind sie verwaltbar
* Object-Files auf einem tmp-Ordner speichern
* Generierergebnisse neben dem Source-Baum speichern.

===Archivieren von Executables===
Aus oben genannten Gründen sollten die Libs und Executables ''nicht'' mit den Sources im SM gemischt werden.
* Die libs und executables könnten einerseits immer aus den Sources generiert werden (wenn alles richtig ist)
* Die libs und executables sind nicht vergleichbar mit üblichen diffs.
* Die libs und executables sind im Code-Umfang zu hoch.

Es ist aber wichtig, libs und exe im Zusammenhang mit einem Checkpoint der Sources zu speichern.
* Als Auslieferungsstand
* Als wichtigen Teststand für Rückrüsten, möglicherweise ein Kandidat für Auslieferung.

Lösung:
* Beim committen eines guten Standes, der angetestet ist, ein kleines batch laufen lassen, das die exes lokal kopiert mit Datumskennzeichnung.
* Damit sind mehrere exes mit Datumsverbindung zum commit lokal vorhanden. Es kann getestet werden.
* '''Auslieferung: Executables und ggf. libs als zip abspeichern''',, siehe oben. Dabei auf den Stand zugreifen, der vorher lokal kopiert wurde und garantiert aus den Sources, die committed wurden, erstellt wurde.
* Nur bei '''Master-Releases''', die entgültig ausgeliefert werden, sollte folgeder Aufwand getrieben werden: Nach erfolgreichem Test die Quellen auf Produktgenerierungsrechner von anderer Person auschecken, neu compilieren, neues Generat erstellen und nochmals testen. Diese Vorgehensweise sichert die Konsistenz der Quellen mit dem Generat und dürfte bei Auslieferungen wichtig sein, dauert aber in der täglichen Fortschrittsarbeit einfach zu lange.

==More as one Repository for one product==
@ident=multiBzr

;Products with more as one components.

:Products are build with more as one components. Any component should be independent from the concretely product, tested as 'component' and may be used in more as one product.

:Conclusion: Do not mix sources, separate it. Therefore any component needs its own bzr archive.

;Sources of components should be located in a subdirectory of the product source tree. It is helpfull to use sub-directories to keep tidiness.

:In linux the sub directory may be a symbolic link. It means, the sources are located anywhere other in the file tree really and they can be maintained outside of the products source tree. In windows a real copy is necessary. But note, that a tool can often gotten the sources from any pathes in the file tree. It is a problem of absolute pathes versus a local sandbox.

:Conclusion: The .bzr repositiory of a component should be located in a sub directory of the product source tree.

:The name of the sub directory should, but doesn't need be identical with the name of the component.

;Getting of source tree of a component, getting its bzr archive

To get the bzr repository for a component of a product, use a simple batch or script file inside the product file tree in that directory, where the components root directory should be stored.

srcJava_Zbnf/ ..... This is the components directory, where its srcJava_Zbnf/.bzr should be located.
getBzr_srcJava_Zbnf.bat ..... This is the batch file to get the bzr archive of the component.

The batch file contains the simple line:

bzrGetVersion srcJava_Zbnf 59

This line should be kept simple and independent of any operation system. Note, that the batchfile works under linux too, if it is set 'executable'. The batchfile calls another script, 'bzrGetVersion' and names the storing directory and the requested version.

The batchfile should be able to locate in the PATH of the computer. It is a thing of installation, not a thing of the designated sources. It contains - for windows - and should be adapted to the concretely conditions at the PC-installation:

@echo off
REM How to get a component's sources:
REM The sources are contained in an bzr archive.
REM The bzr archive is an distributed repository.
REM An archive can exist as a copy on several places,
REM for example at a external hard disk or in network or as a local copy in another drive.
::
REM This is the path to all archives for this computer, correct it if necessary:
set BZR_ARCHIVEPATH=D:/Bzr
::
REM The batch renames the current directory if it is existing yet:
if not exist %1 goto :noCurrent
if exist %1.old rmdir /S/Q %1.old
if exist %1.old goto :nodelOld
ren %1 %1.old
if exist %1 goto :noRename
:noCurrent
::
REM copy the bzr archive and resynchronize all members with the required revision
echo on
bzr checkout %BZR_ARCHIVEPATH%/%1 %1 -r %2
@echo off
if not exist %1 goto :noBzr
goto :ende
::
:noRename
echo can't rename %1 to %1.old. It may be used yet. Do it manually!
pause
goto :ende
::
:nodelOld
echo can't delete %1.old. It may be used yet. Do it manually!
pause
goto :ende
::
:noBzr
echo The bzr archive is not pulled. The version may be faulty or the source path of bzr does not exist.
echo See error messages above.
pause
:ende
exit /B

If you follow the command statements, you can see that an existing directory is kept, of found, but the directory of the component is get newly anytime. It assumes that all bzr archives are located in one directory in the file tree, which can be an external disk too or an network path. See 'BZR_ARCHIVEPATH'.

The content of the archive will be cloned with the 'bzr checkout' command. The files are resynchronzed therefore. An independent working with the files and the cloned archive is possible, if necessary. The working can be pushed to its parent later using 'bzr push', 'bzr merge' etc. But in most cases only the resynchronized version of files are need.

==Mehrere Produkte aus einem Repository==
Das große Thema ist Wiederverwendung (Reuse). Häufig zu Beobachten: Reuse besteht aus copy'n paste and change. Die Quellen wandern also irgendwo anders hin, bzgl SCM auch für den einzelnen besser zu beherrschen - man muss sich nur mit dem beschäftigen, was man selbst hat.

Das ist keine wirkliche Wiederverwendung. Der wirkliche Vorteil des reuse geht dabei verloren:
* Fehler, die in Produkten festgestellt werden, werden in den jeweiligen Modulen korrigiert und sind dann automatisch auch für andere Produkte mit korrigiert, obwohl sie dort ggf. noch gar nicht aufgefallen sind.

Für true-reuse ist es notwendig, die Software-Module so zu bauen, dass sie '''unverändert''' in verschiedenen Produkten verwendbar sind und das Änderungen für alle Produkte nutzbar sind. Das ist eine Frage der Schnittstellen. Die Schnittstellen sind viel wichtiger als die innere Funktionalität. Letztere kann man immer noch verbessern. Schnittstellenänderungen sind kritisch. - Andererseits sind Schnittstellenänderungen auch verträglich, wenn sie formell adaptiert werden können.

Ein shared-Repository in bazaar scheint die Lösung zu bieten, aus einem recht großen Quellenumfang für verschiedene Komponenten verschiedene Quellen herauslösen zu können. Die Komponenten haben selbe gemeinsame Quellen, ggf. in verschiedenen Revisionen, die aber immer abgeglichen werden können sollten. Die Komponenten sind dann Basis für ein Produkt. Komponenten existieren in Form von libs oder jars in Java und können eigenständig getestet werden:

Quellen Komponenten Produkte
viele ===> weniger ===> aus Komponenten
verschiedene überschaubar und Produkt-spezial-Quellen
gebaut.

Wie funktioniert shared-Repository als zentraler Bezug - bin beim testen. (Hartmut)
==Zentrale Ablage für Repositories==
@ident=centralRepos

Man kann immer und überall Repositories haben. Behält man den überblick und synchronisiert diese gegenseitig (push, pull), dann gibt es auch nicht zuviele Seitenzweige.

Jedoch, arbeiten viele Leute mit den Repositories, auch weniger eingeweihte, einfache Nutzer, anderes Problem Archivierung, langjähriges aufheben: Dann sollte an einer definierten Stelle das Master-Repository stehen. Jeder Quellenbearbeiter hat die Pflicht, sich mit dem Master-Repository abzustimmen, also seine Änderungen zu pushen oder von dort zu pullen. Gegebenenfalls sollte eine Person mit der Pflege des Master-Repositories beauftragt sein. Mindestens bei Releaseständen muss diese Person dort bereinigend eingreifen.

===Creating one shared repository in the local space===
The ''local space'' means any external hard disk, network folder or such which is owned by one person, by me. It is my local space, which can be used from some more people in my direct environment.

For any component of sources one shared repository should be created one time. On one sub directory per component: ''bzre: Bazaar -> Start -> Initialize: (x) Shared repository''. An existing plain branch can be pushed to them.

===Creating a branch for working===

* Create a new plain branch at the working position: ''bzre: Bazaar -> Start -> Initialize: (x) Plain branch''.
* Pull from a shared repositiory: ''Button Pull, select the shared repository, select a branch.
** If there are some files already, create the branch at a new position and then move .bzr subdir.

==Branches und dessen Auflösung==
@ident=.branch

;Viele Seitenzweige wegen unterschiedlichen Korrekturen

:Man kann sich auf den Standpunkt stellen, bei Korrekturen für kundenrelevante Software jeweils nur das aufgetretene Fehlerbild zu behandeln, alle anderen Softwareteile unverändert zu lassen. (''Do not touch a running system''). Das ist eine weit verbreitete Vorgehensweise. Folge sind dann sehr viele Seitezweige, die kaum mehr zusammenfließen.

: Primär ist diese Vorgehensweise richtig.

: Es zeigt sich aber, dass eine Änderung in Quellen, auch Restrukturierung, häufig zwar Nacharbeiten erforderlich macht. Diese Nacharbeiten sind aber formal abhandelbar. Man braucht nicht an jeder Stelle einer notwendigen Adaption an geänderte Quellenstände nachzudenken sondern muss nur den Compiler befragen. Kommt keine Fehlermeldung, ist alles in Ordnung. Eine Fehlermeldung soll mit formellen anschauen von Aufrufargumenttypen usw. behebbar sein, ohne dass man in die eigentliche Funktionalität einsteigt. Ist eine solche Nacharbeit möglich, dann kostet diese nur die Zeit der Pflege der Quellen, keine extra Testzeit. Zudem kann die Quellenpflege von jemanden ausgeführt werden, der zwar sehr gute Kenntnisse von Quellen und COmpiler hat, aber keine Tiefenkenntnis für die jeweilige Anwendung haben braucht. Man kann also delegieren.

: In diesem Sinn ist eine Adaption eines Produktes an veränderte Quellen der Komponenten möglich und zweckmäßig. Mann kann dann eher an einem Hauptzweig arbeiten.

: Schlussfolgerung: Schnelle Änderungen ->Seitenzweig, Auflösen dessen, Änderung in Hauptzweig einfließen lassen und Adaption des Produktes auf Hautpzweig der Komponenten ausführen.

===Side branches===
less experience

bzr checkout ../masterlocation . -r REVNR

Gets a part of trunk untio REVNR. It is similar

bzr revert -r REVNR

What is the difference???

bzr update ../masterlocation .

This copies all files in the current dir. It seems to destroy the older-revision side branch (?)

Is there a possibility to checkin changes based on a older revision, without any merge. Only the changed files based on the older revision should be stored in the bazaar repositiory - to compare with other versions or look for changes later. Background: Changing of some source files to bugfix an older software. The reason is not develop and merge.

The workflow of develop and bugfix in a decentralized team is explained in
* [[http://doc.bazaar.canonical.com/latest/en/user-guide/organizing_branches.html doc.bazaar.canonical.com/latest/en/user-guide/organizing_branches]].

But this is not the problem of side branches, more the problem of development in team.

'''An side glance to git''':

$ git branch bugfix

creates a branch named 'bugfix' in the same only one repository. It is a branch with the same revision as the current one.

$ git checkout bugfix
now switches to the named branch.

$ git reset -q COMMITNR

This moves the current revision of the current branch (it is 'bugfix' to a older revision. COMMITNR is the hash number of any commit, see git log

$ git checkout .

resynchronized all files of the selected revision.

...changing any files and

$ git commit

builds a side branch in the repository (archive).

Now a switch to another branch and its revision is possible in the same sandbox to work with it:

$ git checkout master

now switches back to this named branch and resynchronizes all files. Work with it, commit etc.

If there should be worked only at one side branch to any time, and be worked at another side branch to another time, then only one sandbox is necessary. You can switch between the branches. The files are changed, all files are stored in the git archive.

If there should be worked with more as one side branches to the same time, a copy of the git archive is necessary. The archive and the files should be stored at different places on the hard disk, or at more as one computer etc. It isn't recommended to use the same git archive, may be with an symbolic link in linux. The disadvantage is: The git archive knows the current branch, which was selected with 'checkout'. If you want to use only one archive but more as one sandbox for the files, you can have a symbolic link in the sandboxes to the same archive. But then you have to switch between the side-branches before any status, commit etc. action are done in one of the sandboxes. But be attentive to your files. You may overwrite they if you are careless. You can't do that at the same time, maybe more as one people in network. It will be confused if they are work concurrently.

I haven't test yet, but it shouldn't a problem to merge the more as one git archives without conflicts, if only one archive has changed only one side branch.

[[http://www.vishia.org/SwEng/pictures/git-side-branch-example.jpg Image: example side branches in git]]

'''Now back to bazaar''':

John A Meinel proposed the following answer:

If you want to commit new changes based on an older revision, you generally want to start a new branch. So something like

bzr branch master feature -r OLD
cd feature
bzr commit

If you are using a checkout you can do

cd checkout
bzr branch --switch -r OLD ../master ../feature

TODO test

Bazaar-Notes

Admin — Sat, 06 Aug 2011 06:19:44 GMT

Admin: /* Side branches */ Experience with image on foreign internet page

@ident=Bazaar_notes

Links:
* [[Bazaar-guide]]: a guide to use Bazaar.

This size is in german, because it is discussed in a german team. It will be presented in english in the future. TODO

==Kurzer Abriss, Arbeit mit MKSSI, git, mercurial, Bazaar==

Hartmut: MKSSI ist seit über 10 Jahren bei mir in Gebrauch.
* Nur auf Arbeit, zentrale Administration,
* Die MKSSI-Software wird normalerweise nicht ständig updated. Das Arbeiten ist nicht sehr schnell, eher etwas für ordentliche Pflege.
* Wird gemacht, für die Versionen, die herausgegeben werden. Nicht für stündliche kleine Änderungen. Da wäre der Arbeitsaufwand zu hoch.

Hartmut: git war das erste der 'dritten Generation' für mich.
* Geht ganz gut, init commit, alles ganz einfach
* Nachschauen der Änderungen: Hier ist die GUI (gitk) nicht sehr bedienerfreundlich. Die schnelle Tastaturbedienung ist mangelhaft, der Tastaturfokus ist im falschen Teilfenster. Immer mit Maus schieben ...
* Linux-like cmdline-Bedienung auf Windows-PC ist für mich eher interessant.

Hartmut: mercurial - ähnlich wie git, nur eher für windows, eigentlich sehr ähnlich git.

Hartmut: Bazaar gefällt mir persönlich wegen der GUI besser.

Hartmut: Alle drei Systeme sind aber funktionell eher ähnlich. Ich pflege Quellen in Bazaar, um sie dann auch in hg zu committen, mit selbigem commit-Text wie in Bazaar zuvor zusammengestellt. Das ist nur ein Aufruf. Ein Hg-Archiv beispielsweise für CRuntimeJavalike liegt auf [[https://bitbucket.org/jchartmut/cruntimejavalike bitbucket.org/jchartmut/cruntimejavalike]]. Hg deshalb, weil die bitbucket-Seite nur hg unterstützt. Der Aufwand, in hg doppelt zu pflegen, ist kaum erhebenswert.

;Commit-Text zusammenstellen

:Vorderhand geht es beim Commit-text darum: Was leistet diese Version insgesamt, unterschied zur Vorversion. In der Zweiten Linie geht es aber um die Änderung in den einzelnen Files.

:Sind im Commit sehr viele Files enthalten, dann handelt es sich meist um das Ergebnis eines Refactoring wegen einer Änderung. Solche Änderungen brauchen in den Quellfiles nicht vermerkt werden, zuviel Aufwand, uninteressant.

:Sind dagegen wenige Files geändert, dann lag meist auch eine Änderung der Funktionalität vor. Diese sollte unabhängig vom Commit in den Quellfiles notiert werden. Hier hilft aber die Differenzanzeige, um während des Commit die Änderungen in den Files zu vermerken. Man kann einen passenden Commit-Text zusammenstellen, dabei die Änderung der Einzelfiles betrachten und dabei in den Einzelfiles Änderungen notieren (log des Files).

:Ein automatisches Eintragen der Änderung in den Files aus dem checkin-Textes aus der Arbeit mit dem Source-Integrity-System produziert meist Einträge in den Files, die die Änderungen schlecht abbilden. Das liegt daran, weil der Arbeitsaufwand für jeden Einzelfile zu hoch ist. Dieses automatische Eintragen ist aber eine häufig verwendete oder voreingestellte Methode bei MKSSI & co.

: Der Arbeitsaufwand bei manuellem Eintragen in den File ist deshalb bei Bazaar geringer, weil
:* Es gibt eine schnelle Übersicht, welche Files betroffen sind. Einfacher Knopfdruck für Viewdiff. Man kann schnell auswählen, bei welchen Files ggf. gleiche Einträge überhaupt notwendig sind. Nicht bei allen geänderten.
:* Mit den Files, die keine wesentlichen Änderungen enthalten sondern nur Anpassungen an Änderungen anderer Files, braucht man sich also gar nicht beschäftigen.
:* Die Änderung im File eingetragen und per Zwischenablage auch im Commit-Text abgelegt ist dann eigentlich nur einmaliger Aufwand, nicht zweimal.
:* Wenn es wesentliche Änderungen sind, dann ist die Beschreibung der Änderung auch ein schöpferischer und nicht formeller Akt. Dann lohnt es sich auch, die entsprechend notwendige Zeit aufzubringen. Möglicherweise wird man bei der Änderungsbeschreibung im File auch noch weitere dabei entdeckte Pflegekorrekturen anbringen, die insgesamt die Quelle weiter aufwerten. Dann hat es sich sowieso gelohnt.

==Source Content Management oder hart archivieren? Nur Quellen im SCM?==

Eine harte Archivierung ist das Verpacken der Files auf einem Datenträger. Da das Zip-format sich als langjährig beständig erwiesen hat, kann man ganze File-Bäume zippen und irgendwo aufheben.

Nachteil: Keine Unterstützung für Diff-View außer auspacken und mit einem Diff-tool vergleichen. Der Total-Commander eignet sich dazu allerdings recht gut, da er in beiden Paneelen in zip-Archive tief eintauchen kann.

Vorteil: Unabhängig von einem Tool, die Files einer Version sind zusammengebunden einfach da. Es hat sich schon oft als günstig erwiesen, lange Jahre zurückliegende Files nicht mit den damaligen Tools aufrollen zu müssen sondern einfach entzippen.

Der Vorteil für die Langjährigkeit sollte bedacht werden.

=>Schlussfolgerung: Ab und zu zippen und wegpacken, mindestens bei wichtigen Releaseständen. Aber unnütze zipfiles auch mal löschen.

=>Schlussfolgerung: Für akutelle Softwareentwicklung jedenfalls ein Source-Integrity-Tool nutzen, Zippen nur zusätzlich.

===Verzeichnissstuktur-Rückschluss===

Sowohl für das Zippen als auch für Sourcenpflege, Sourcenaustausch usw. liegt der tatsächliche Umfang von Sources insgesamt meist in einem Bereich von wenigen Megabyte. Damit ist der Datenaustausch mindestens erleichtert. Wenn man in die selbe Verzeichnisstruktur in der Quellen liegen noch hineintue:
* Objects
* erzeugte executable und umfangreiche Datenbasis-Files (Visual Studio ncb-Files und dergleichen)
* logfiles, Output-Files beim Testen
* alte Archive (zips)

dann springt der Umfang des Verzeichnisbausms von wenigen Megabyte ganz schnell auf -zig Megabyte. Das Problem merkt man
* beim zippen (ganz schnell mal ablegen zum späteren Vergleich)
* beim Vergleichen (alle Obj erscheinen als geändert, alles rot, erst mal schaun was das ist)
* bei der Pflege der Sources in einem SM-system (Source Management): viele nicht erfasste files: Sind die wichtig? Ach, sind nur Obj, doch ein wichtige wird übersehen.

=>Schlussfolgerung: Möglichst Sources von Testfiles und Executables trennen. Die wenigen Files, die nicht trennbar sind (weil die Tools sie ins aktuelle Verzeichnis legen), in einer ignore-Liste erfassen, ggf. beim zippen ausschließen usw. Sind es wenige, dann sind sie verwaltbar
* Object-Files auf einem tmp-Ordner speichern
* Generierergebnisse neben dem Source-Baum speichern.

===Archivieren von Executables===
Aus oben genannten Gründen sollten die Libs und Executables ''nicht'' mit den Sources im SM gemischt werden.
* Die libs und executables könnten einerseits immer aus den Sources generiert werden (wenn alles richtig ist)
* Die libs und executables sind nicht vergleichbar mit üblichen diffs.
* Die libs und executables sind im Code-Umfang zu hoch.

Es ist aber wichtig, libs und exe im Zusammenhang mit einem Checkpoint der Sources zu speichern.
* Als Auslieferungsstand
* Als wichtigen Teststand für Rückrüsten, möglicherweise ein Kandidat für Auslieferung.

Lösung:
* Beim committen eines guten Standes, der angetestet ist, ein kleines batch laufen lassen, das die exes lokal kopiert mit Datumskennzeichnung.
* Damit sind mehrere exes mit Datumsverbindung zum commit lokal vorhanden. Es kann getestet werden.
* '''Auslieferung: Executables und ggf. libs als zip abspeichern''',, siehe oben. Dabei auf den Stand zugreifen, der vorher lokal kopiert wurde und garantiert aus den Sources, die committed wurden, erstellt wurde.
* Nur bei '''Master-Releases''', die entgültig ausgeliefert werden, sollte folgeder Aufwand getrieben werden: Nach erfolgreichem Test die Quellen auf Produktgenerierungsrechner von anderer Person auschecken, neu compilieren, neues Generat erstellen und nochmals testen. Diese Vorgehensweise sichert die Konsistenz der Quellen mit dem Generat und dürfte bei Auslieferungen wichtig sein, dauert aber in der täglichen Fortschrittsarbeit einfach zu lange.

==Mehrere Repositories für ein Produkt==
@ident=multiBzr

;Produkt aus mehreren Quell-Komponenten

:Produkt (Executable etc.) besteht aus Quellen aus mehreren Projekten (Komponenten).
Die Quell-Komponenten sind relativ unabhängig und werden an anderer Stelle aus anderen Zusammenhängen ebenfalls gepflegt.

:Schlussfolgerung: Nicht mischen, weil sonst kein Durchblick wo was gepflegt wird.
Jede Quell-Komponente wird in ihrem eigenem .bzr-repository gepflegt.

;Quell-Komponenten befinden sich im Produkt-Sourcenbaum in jeweils bestimmten Unterverzeichnissen

:Unterverzeichnisordnung ist zweckmäßig, weil damit auch im Produkt-Verzeichnis ordnung herrscht.

:In linux kann dort ein symbolischer Link stehen, d.h. Quellen stehen eigentlich ganz woanders. In Windows ist eine Kopie der Komponenten-Quellen im Produkt-Verzeichnisbaum vorhanden.

: In windows kann aber auch ggf. eine Quellkomponente auch ganz woanders stehen, beispielsweise kann bei Eclipse ein Verzeichnis mit absolutem Pfad von irgendwo dem Projkekt hinzugefügt werden. Das ganze ist eine Sache von Pfaden, die irgendwo definiert sein müssen.

:Schlussfolgerung: Das .bzr-Repository der Quellen der Komponente sollte in dem Unterverzeichnis stehen.

: Folglich hängt der Name des Unterverzeichnisses nicht an der Quellkomponente, kann im Produkt auch beliebig gewählt werden. Folglich kann die Quellkomponente auch irgendwo anders stehen, also kein Unterverzeichnis sondern absoluter Pfad. Der absolute Pfad wird beim editieren/generieren beachtet.

Das spricht insgesamt dafür, ein Produkt aus mehreren Bazaar-Quell-Repositories zusammenzusetzen.

==Mehrere Produkte aus einem Repository==
Das große Thema ist Wiederverwendung (Reuse). Häufig zu Beobachten: Reuse besteht aus copy'n paste and change. Die Quellen wandern also irgendwo anders hin, bzgl SCM auch für den einzelnen besser zu beherrschen - man muss sich nur mit dem beschäftigen, was man selbst hat.

Das ist keine wirkliche Wiederverwendung. Der wirkliche Vorteil des reuse geht dabei verloren:
* Fehler, die in Produkten festgestellt werden, werden in den jeweiligen Modulen korrigiert und sind dann automatisch auch für andere Produkte mit korrigiert, obwohl sie dort ggf. noch gar nicht aufgefallen sind.

Für true-reuse ist es notwendig, die Software-Module so zu bauen, dass sie '''unverändert''' in verschiedenen Produkten verwendbar sind und das Änderungen für alle Produkte nutzbar sind. Das ist eine Frage der Schnittstellen. Die Schnittstellen sind viel wichtiger als die innere Funktionalität. Letztere kann man immer noch verbessern. Schnittstellenänderungen sind kritisch. - Andererseits sind Schnittstellenänderungen auch verträglich, wenn sie formell adaptiert werden können.

Ein shared-Repository in bazaar scheint die Lösung zu bieten, aus einem recht großen Quellenumfang für verschiedene Komponenten verschiedene Quellen herauslösen zu können. Die Komponenten haben selbe gemeinsame Quellen, ggf. in verschiedenen Revisionen, die aber immer abgeglichen werden können sollten. Die Komponenten sind dann Basis für ein Produkt. Komponenten existieren in Form von libs oder jars in Java und können eigenständig getestet werden:

Quellen Komponenten Produkte
viele ===> weniger ===> aus Komponenten
verschiedene überschaubar und Produkt-spezial-Quellen
gebaut.

Wie funktioniert shared-Repository als zentraler Bezug - bin beim testen. (Hartmut)
==Zentrale Ablage für Repositories==
@ident=centralRepos

Man kann immer und überall Repositories haben. Behält man den überblick und synchronisiert diese gegenseitig (push, pull), dann gibt es auch nicht zuviele Seitenzweige.

Jedoch, arbeiten viele Leute mit den Repositories, auch weniger eingeweihte, einfache Nutzer, anderes Problem Archivierung, langjähriges aufheben: Dann sollte an einer definierten Stelle das Master-Repository stehen. Jeder Quellenbearbeiter hat die Pflicht, sich mit dem Master-Repository abzustimmen, also seine Änderungen zu pushen oder von dort zu pullen. Gegebenenfalls sollte eine Person mit der Pflege des Master-Repositories beauftragt sein. Mindestens bei Releaseständen muss diese Person dort bereinigend eingreifen.

===Creating one shared repository in the local space===
The ''local space'' means any external hard disk, network folder or such which is owned by one person, by me. It is my local space, which can be used from some more people in my direct environment.

For any component of sources one shared repository should be created one time. On one sub directory per component: ''bzre: Bazaar -> Start -> Initialize: (x) Shared repository''. An existing plain branch can be pushed to them.

===Creating a branch for working===

* Create a new plain branch at the working position: ''bzre: Bazaar -> Start -> Initialize: (x) Plain branch''.
* Pull from a shared repositiory: ''Button Pull, select the shared repository, select a branch.
** If there are some files already, create the branch at a new position and then move .bzr subdir.

==Branches und dessen Auflösung==
@ident=.branch

;Viele Seitenzweige wegen unterschiedlichen Korrekturen

:Man kann sich auf den Standpunkt stellen, bei Korrekturen für kundenrelevante Software jeweils nur das aufgetretene Fehlerbild zu behandeln, alle anderen Softwareteile unverändert zu lassen. (''Do not touch a running system''). Das ist eine weit verbreitete Vorgehensweise. Folge sind dann sehr viele Seitezweige, die kaum mehr zusammenfließen.

: Primär ist diese Vorgehensweise richtig.

: Es zeigt sich aber, dass eine Änderung in Quellen, auch Restrukturierung, häufig zwar Nacharbeiten erforderlich macht. Diese Nacharbeiten sind aber formal abhandelbar. Man braucht nicht an jeder Stelle einer notwendigen Adaption an geänderte Quellenstände nachzudenken sondern muss nur den Compiler befragen. Kommt keine Fehlermeldung, ist alles in Ordnung. Eine Fehlermeldung soll mit formellen anschauen von Aufrufargumenttypen usw. behebbar sein, ohne dass man in die eigentliche Funktionalität einsteigt. Ist eine solche Nacharbeit möglich, dann kostet diese nur die Zeit der Pflege der Quellen, keine extra Testzeit. Zudem kann die Quellenpflege von jemanden ausgeführt werden, der zwar sehr gute Kenntnisse von Quellen und COmpiler hat, aber keine Tiefenkenntnis für die jeweilige Anwendung haben braucht. Man kann also delegieren.

: In diesem Sinn ist eine Adaption eines Produktes an veränderte Quellen der Komponenten möglich und zweckmäßig. Mann kann dann eher an einem Hauptzweig arbeiten.

: Schlussfolgerung: Schnelle Änderungen ->Seitenzweig, Auflösen dessen, Änderung in Hauptzweig einfließen lassen und Adaption des Produktes auf Hautpzweig der Komponenten ausführen.

===Side branches===
less experience

bzr checkout ../masterlocation . -r REVNR

Gets a part of trunk untio REVNR. It is similar

bzr revert -r REVNR

What is the difference???

bzr update ../masterlocation .

This copies all files in the current dir. It seems to destroy the older-revision side branch (?)

Is there a possibility to checkin changes based on a older revision, without any merge. Only the changed files based on the older revision should be stored in the bazaar repositiory - to compare with other versions or look for changes later. Background: Changing of some source files to bugfix an older software. The reason is not develop and merge.

The workflow of develop and bugfix in a decentralized team is explained in
* [[http://doc.bazaar.canonical.com/latest/en/user-guide/organizing_branches.html doc.bazaar.canonical.com/latest/en/user-guide/organizing_branches]].

But this is not the problem of side branches, more the problem of development in team.

'''An side glance to git''':

$ git branch bugfix

creates a branch named 'bugfix' in the same only one repository. It is a branch with the same revision as the current one.

$ git checkout bugfix
now switches to the named branch.

$ git reset -q COMMITNR

This moves the current revision of the current branch (it is 'bugfix' to a older revision. COMMITNR is the hash number of any commit, see git log

$ git checkout .

resynchronized all files of the selected revision.

...changing any files and

$ git commit

builds a side branch in the repository (archive).

Now a switch to another branch and its revision is possible in the same sandbox to work with it:

$ git checkout master

now switches back to this named branch and resynchronizes all files. Work with it, commit etc.

If there should be worked only at one side branch to any time, and be worked at another side branch to another time, then only one sandbox is necessary. You can switch between the branches. The files are changed, all files are stored in the git archive.

If there should be worked with more as one side branches to the same time, a copy of the git archive is necessary. The archive and the files should be stored at different places on the hard disk, or at more as one computer etc. It isn't recommended to use the same git archive, may be with an symbolic link in linux. The disadvantage is: The git archive knows the current branch, which was selected with 'checkout'. If you want to use only one archive but more as one sandbox for the files, you can have a symbolic link in the sandboxes to the same archive. But then you have to switch between the side-branches before any status, commit etc. action are done in one of the sandboxes. But be attentive to your files. You may overwrite they if you are careless. You can't do that at the same time, maybe more as one people in network. It will be confused if they are work concurrently.

I haven't test yet, but it shouldn't a problem to merge the more as one git archives without conflicts, if only one archive has changed only one side branch.

[[http://www.vishia.org/SwEng/pictures/git-side-branch-example.jpg Image: example side branches in git]]

'''Now back to bazaar''':

John A Meinel proposed the following answer:

If you want to commit new changes based on an older revision, you generally want to start a new branch. So something like

bzr branch master feature -r OLD
cd feature
bzr commit

If you are using a checkout you can do

cd checkout
bzr branch --switch -r OLD ../master ../feature

TODO test

Bazaar-Notes

Admin — Fri, 22 Jul 2011 20:54:36 GMT

Admin: test image

@ident=Bazaar_notes

Links:
* [[Bazaar-guide]]: a guide to use Bazaar.

This size is in german, because it is discussed in a german team. It will be presented in english in the future. TODO

==Kurzer Abriss, Arbeit mit MKSSI, git, mercurial, Bazaar==

Hartmut: MKSSI ist seit über 10 Jahren bei mir in Gebrauch.
* Nur auf Arbeit, zentrale Administration,
* Die MKSSI-Software wird normalerweise nicht ständig updated. Das Arbeiten ist nicht sehr schnell, eher etwas für ordentliche Pflege.
* Wird gemacht, für die Versionen, die herausgegeben werden. Nicht für stündliche kleine Änderungen. Da wäre der Arbeitsaufwand zu hoch.

Hartmut: git war das erste der 'dritten Generation' für mich.
* Geht ganz gut, init commit, alles ganz einfach
* Nachschauen der Änderungen: Hier ist die GUI (gitk) nicht sehr bedienerfreundlich. Die schnelle Tastaturbedienung ist mangelhaft, der Tastaturfokus ist im falschen Teilfenster. Immer mit Maus schieben ...
* Linux-like cmdline-Bedienung auf Windows-PC ist für mich eher interessant.

Hartmut: mercurial - ähnlich wie git, nur eher für windows, eigentlich sehr ähnlich git.

Hartmut: Bazaar gefällt mir persönlich wegen der GUI besser.

Hartmut: Alle drei Systeme sind aber funktionell eher ähnlich. Ich pflege Quellen in Bazaar, um sie dann auch in hg zu committen, mit selbigem commit-Text wie in Bazaar zuvor zusammengestellt. Das ist nur ein Aufruf. Ein Hg-Archiv beispielsweise für CRuntimeJavalike liegt auf [[https://bitbucket.org/jchartmut/cruntimejavalike bitbucket.org/jchartmut/cruntimejavalike]]. Hg deshalb, weil die bitbucket-Seite nur hg unterstützt. Der Aufwand, in hg doppelt zu pflegen, ist kaum erhebenswert.

;Commit-Text zusammenstellen

:Vorderhand geht es beim Commit-text darum: Was leistet diese Version insgesamt, unterschied zur Vorversion. In der Zweiten Linie geht es aber um die Änderung in den einzelnen Files.

:Sind im Commit sehr viele Files enthalten, dann handelt es sich meist um das Ergebnis eines Refactoring wegen einer Änderung. Solche Änderungen brauchen in den Quellfiles nicht vermerkt werden, zuviel Aufwand, uninteressant.

:Sind dagegen wenige Files geändert, dann lag meist auch eine Änderung der Funktionalität vor. Diese sollte unabhängig vom Commit in den Quellfiles notiert werden. Hier hilft aber die Differenzanzeige, um während des Commit die Änderungen in den Files zu vermerken. Man kann einen passenden Commit-Text zusammenstellen, dabei die Änderung der Einzelfiles betrachten und dabei in den Einzelfiles Änderungen notieren (log des Files).

:Ein automatisches Eintragen der Änderung in den Files aus dem checkin-Textes aus der Arbeit mit dem Source-Integrity-System produziert meist Einträge in den Files, die die Änderungen schlecht abbilden. Das liegt daran, weil der Arbeitsaufwand für jeden Einzelfile zu hoch ist. Dieses automatische Eintragen ist aber eine häufig verwendete oder voreingestellte Methode bei MKSSI & co.

: Der Arbeitsaufwand bei manuellem Eintragen in den File ist deshalb bei Bazaar geringer, weil
:* Es gibt eine schnelle Übersicht, welche Files betroffen sind. Einfacher Knopfdruck für Viewdiff. Man kann schnell auswählen, bei welchen Files ggf. gleiche Einträge überhaupt notwendig sind. Nicht bei allen geänderten.
:* Mit den Files, die keine wesentlichen Änderungen enthalten sondern nur Anpassungen an Änderungen anderer Files, braucht man sich also gar nicht beschäftigen.
:* Die Änderung im File eingetragen und per Zwischenablage auch im Commit-Text abgelegt ist dann eigentlich nur einmaliger Aufwand, nicht zweimal.
:* Wenn es wesentliche Änderungen sind, dann ist die Beschreibung der Änderung auch ein schöpferischer und nicht formeller Akt. Dann lohnt es sich auch, die entsprechend notwendige Zeit aufzubringen. Möglicherweise wird man bei der Änderungsbeschreibung im File auch noch weitere dabei entdeckte Pflegekorrekturen anbringen, die insgesamt die Quelle weiter aufwerten. Dann hat es sich sowieso gelohnt.

==Source Content Management oder hart archivieren? Nur Quellen im SCM?==

Eine harte Archivierung ist das Verpacken der Files auf einem Datenträger. Da das Zip-format sich als langjährig beständig erwiesen hat, kann man ganze File-Bäume zippen und irgendwo aufheben.

Nachteil: Keine Unterstützung für Diff-View außer auspacken und mit einem Diff-tool vergleichen. Der Total-Commander eignet sich dazu allerdings recht gut, da er in beiden Paneelen in zip-Archive tief eintauchen kann.

Vorteil: Unabhängig von einem Tool, die Files einer Version sind zusammengebunden einfach da. Es hat sich schon oft als günstig erwiesen, lange Jahre zurückliegende Files nicht mit den damaligen Tools aufrollen zu müssen sondern einfach entzippen.

Der Vorteil für die Langjährigkeit sollte bedacht werden.

=>Schlussfolgerung: Ab und zu zippen und wegpacken, mindestens bei wichtigen Releaseständen. Aber unnütze zipfiles auch mal löschen.

=>Schlussfolgerung: Für akutelle Softwareentwicklung jedenfalls ein Source-Integrity-Tool nutzen, Zippen nur zusätzlich.

===Verzeichnissstuktur-Rückschluss===

Sowohl für das Zippen als auch für Sourcenpflege, Sourcenaustausch usw. liegt der tatsächliche Umfang von Sources insgesamt meist in einem Bereich von wenigen Megabyte. Damit ist der Datenaustausch mindestens erleichtert. Wenn man in die selbe Verzeichnisstruktur in der Quellen liegen noch hineintue:
* Objects
* erzeugte executable und umfangreiche Datenbasis-Files (Visual Studio ncb-Files und dergleichen)
* logfiles, Output-Files beim Testen
* alte Archive (zips)

dann springt der Umfang des Verzeichnisbausms von wenigen Megabyte ganz schnell auf -zig Megabyte. Das Problem merkt man
* beim zippen (ganz schnell mal ablegen zum späteren Vergleich)
* beim Vergleichen (alle Obj erscheinen als geändert, alles rot, erst mal schaun was das ist)
* bei der Pflege der Sources in einem SM-system (Source Management): viele nicht erfasste files: Sind die wichtig? Ach, sind nur Obj, doch ein wichtige wird übersehen.

=>Schlussfolgerung: Möglichst Sources von Testfiles und Executables trennen. Die wenigen Files, die nicht trennbar sind (weil die Tools sie ins aktuelle Verzeichnis legen), in einer ignore-Liste erfassen, ggf. beim zippen ausschließen usw. Sind es wenige, dann sind sie verwaltbar
* Object-Files auf einem tmp-Ordner speichern
* Generierergebnisse neben dem Source-Baum speichern.

===Archivieren von Executables===
Aus oben genannten Gründen sollten die Libs und Executables ''nicht'' mit den Sources im SM gemischt werden.
* Die libs und executables könnten einerseits immer aus den Sources generiert werden (wenn alles richtig ist)
* Die libs und executables sind nicht vergleichbar mit üblichen diffs.
* Die libs und executables sind im Code-Umfang zu hoch.

Es ist aber wichtig, libs und exe im Zusammenhang mit einem Checkpoint der Sources zu speichern.
* Als Auslieferungsstand
* Als wichtigen Teststand für Rückrüsten, möglicherweise ein Kandidat für Auslieferung.

Lösung:
* Beim committen eines guten Standes, der angetestet ist, ein kleines batch laufen lassen, das die exes lokal kopiert mit Datumskennzeichnung.
* Damit sind mehrere exes mit Datumsverbindung zum commit lokal vorhanden. Es kann getestet werden.
* '''Auslieferung: Executables und ggf. libs als zip abspeichern''',, siehe oben. Dabei auf den Stand zugreifen, der vorher lokal kopiert wurde und garantiert aus den Sources, die committed wurden, erstellt wurde.
* Nur bei '''Master-Releases''', die entgültig ausgeliefert werden, sollte folgeder Aufwand getrieben werden: Nach erfolgreichem Test die Quellen auf Produktgenerierungsrechner von anderer Person auschecken, neu compilieren, neues Generat erstellen und nochmals testen. Diese Vorgehensweise sichert die Konsistenz der Quellen mit dem Generat und dürfte bei Auslieferungen wichtig sein, dauert aber in der täglichen Fortschrittsarbeit einfach zu lange.

==Mehrere Repositories für ein Produkt==
@ident=multiBzr

;Produkt aus mehreren Quell-Komponenten

:Produkt (Executable etc.) besteht aus Quellen aus mehreren Projekten (Komponenten).
Die Quell-Komponenten sind relativ unabhängig und werden an anderer Stelle aus anderen Zusammenhängen ebenfalls gepflegt.

:Schlussfolgerung: Nicht mischen, weil sonst kein Durchblick wo was gepflegt wird.
Jede Quell-Komponente wird in ihrem eigenem .bzr-repository gepflegt.

;Quell-Komponenten befinden sich im Produkt-Sourcenbaum in jeweils bestimmten Unterverzeichnissen

:Unterverzeichnisordnung ist zweckmäßig, weil damit auch im Produkt-Verzeichnis ordnung herrscht.

:In linux kann dort ein symbolischer Link stehen, d.h. Quellen stehen eigentlich ganz woanders. In Windows ist eine Kopie der Komponenten-Quellen im Produkt-Verzeichnisbaum vorhanden.

: In windows kann aber auch ggf. eine Quellkomponente auch ganz woanders stehen, beispielsweise kann bei Eclipse ein Verzeichnis mit absolutem Pfad von irgendwo dem Projkekt hinzugefügt werden. Das ganze ist eine Sache von Pfaden, die irgendwo definiert sein müssen.

:Schlussfolgerung: Das .bzr-Repository der Quellen der Komponente sollte in dem Unterverzeichnis stehen.

: Folglich hängt der Name des Unterverzeichnisses nicht an der Quellkomponente, kann im Produkt auch beliebig gewählt werden. Folglich kann die Quellkomponente auch irgendwo anders stehen, also kein Unterverzeichnis sondern absoluter Pfad. Der absolute Pfad wird beim editieren/generieren beachtet.

Das spricht insgesamt dafür, ein Produkt aus mehreren Bazaar-Quell-Repositories zusammenzusetzen.

==Mehrere Produkte aus einem Repository==
Das große Thema ist Wiederverwendung (Reuse). Häufig zu Beobachten: Reuse besteht aus copy'n paste and change. Die Quellen wandern also irgendwo anders hin, bzgl SCM auch für den einzelnen besser zu beherrschen - man muss sich nur mit dem beschäftigen, was man selbst hat.

Das ist keine wirkliche Wiederverwendung. Der wirkliche Vorteil des reuse geht dabei verloren:
* Fehler, die in Produkten festgestellt werden, werden in den jeweiligen Modulen korrigiert und sind dann automatisch auch für andere Produkte mit korrigiert, obwohl sie dort ggf. noch gar nicht aufgefallen sind.

Für true-reuse ist es notwendig, die Software-Module so zu bauen, dass sie '''unverändert''' in verschiedenen Produkten verwendbar sind und das Änderungen für alle Produkte nutzbar sind. Das ist eine Frage der Schnittstellen. Die Schnittstellen sind viel wichtiger als die innere Funktionalität. Letztere kann man immer noch verbessern. Schnittstellenänderungen sind kritisch. - Andererseits sind Schnittstellenänderungen auch verträglich, wenn sie formell adaptiert werden können.

Ein shared-Repository in bazaar scheint die Lösung zu bieten, aus einem recht großen Quellenumfang für verschiedene Komponenten verschiedene Quellen herauslösen zu können. Die Komponenten haben selbe gemeinsame Quellen, ggf. in verschiedenen Revisionen, die aber immer abgeglichen werden können sollten. Die Komponenten sind dann Basis für ein Produkt. Komponenten existieren in Form von libs oder jars in Java und können eigenständig getestet werden:

Quellen Komponenten Produkte
viele ===> weniger ===> aus Komponenten
verschiedene überschaubar und Produkt-spezial-Quellen
gebaut.

Wie funktioniert shared-Repository als zentraler Bezug - bin beim testen. (Hartmut)
==Zentrale Ablage für Repositories==
@ident=centralRepos

Man kann immer und überall Repositories haben. Behält man den überblick und synchronisiert diese gegenseitig (push, pull), dann gibt es auch nicht zuviele Seitenzweige.

Jedoch, arbeiten viele Leute mit den Repositories, auch weniger eingeweihte, einfache Nutzer, anderes Problem Archivierung, langjähriges aufheben: Dann sollte an einer definierten Stelle das Master-Repository stehen. Jeder Quellenbearbeiter hat die Pflicht, sich mit dem Master-Repository abzustimmen, also seine Änderungen zu pushen oder von dort zu pullen. Gegebenenfalls sollte eine Person mit der Pflege des Master-Repositories beauftragt sein. Mindestens bei Releaseständen muss diese Person dort bereinigend eingreifen.

===Creating one shared repository in the local space===
The ''local space'' means any external hard disk, network folder or such which is owned by one person, by me. It is my local space, which can be used from some more people in my direct environment.

For any component of sources one shared repository should be created one time. On one sub directory per component: ''bzre: Bazaar -> Start -> Initialize: (x) Shared repository''. An existing plain branch can be pushed to them.

===Creating a branch for working===

* Create a new plain branch at the working position: ''bzre: Bazaar -> Start -> Initialize: (x) Plain branch''.
* Pull from a shared repositiory: ''Button Pull, select the shared repository, select a branch.
** If there are some files already, create the branch at a new position and then move .bzr subdir.

==Branches und dessen Auflösung==
@ident=.branch

;Viele Seitenzweige wegen unterschiedlichen Korrekturen

:Man kann sich auf den Standpunkt stellen, bei Korrekturen für kundenrelevante Software jeweils nur das aufgetretene Fehlerbild zu behandeln, alle anderen Softwareteile unverändert zu lassen. (''Do not touch a running system''). Das ist eine weit verbreitete Vorgehensweise. Folge sind dann sehr viele Seitezweige, die kaum mehr zusammenfließen.

: Primär ist diese Vorgehensweise richtig.

: Es zeigt sich aber, dass eine Änderung in Quellen, auch Restrukturierung, häufig zwar Nacharbeiten erforderlich macht. Diese Nacharbeiten sind aber formal abhandelbar. Man braucht nicht an jeder Stelle einer notwendigen Adaption an geänderte Quellenstände nachzudenken sondern muss nur den Compiler befragen. Kommt keine Fehlermeldung, ist alles in Ordnung. Eine Fehlermeldung soll mit formellen anschauen von Aufrufargumenttypen usw. behebbar sein, ohne dass man in die eigentliche Funktionalität einsteigt. Ist eine solche Nacharbeit möglich, dann kostet diese nur die Zeit der Pflege der Quellen, keine extra Testzeit. Zudem kann die Quellenpflege von jemanden ausgeführt werden, der zwar sehr gute Kenntnisse von Quellen und COmpiler hat, aber keine Tiefenkenntnis für die jeweilige Anwendung haben braucht. Man kann also delegieren.

: In diesem Sinn ist eine Adaption eines Produktes an veränderte Quellen der Komponenten möglich und zweckmäßig. Mann kann dann eher an einem Hauptzweig arbeiten.

: Schlussfolgerung: Schnelle Änderungen ->Seitenzweig, Auflösen dessen, Änderung in Hauptzweig einfließen lassen und Adaption des Produktes auf Hautpzweig der Komponenten ausführen.

===Side branches===
less experience

bzr checkout ../masterlocation . -r REVNR

Gets a part of trunk untio REVNR. It is similar

bzr revert -r REVNR

What is the difference???

bzr update ../masterlocation .

This copies all files in the current dir. It seems to destroy the older-revision side branch (?)

Is there a possibility to checkin changes based on a older revision, without any merge. Only the changed files based on the older revision should be stored in the bazaar repositiory - to compare with other versions or look for changes later. Background: Changing of some source files to bugfix an older software. The reason is not develop and merge.

The workflow of develop and bugfix in a decentralized team is explained in
* [[http://doc.bazaar.canonical.com/latest/en/user-guide/organizing_branches.html doc.bazaar.canonical.com/latest/en/user-guide/organizing_branches]].

But this is not the problem of side branches, more the problem of development in team.

'''An side glance to git''':

$ git branch bugfix

creates a branch named 'bugfix' in the same only one repository. It is a branch with the same revision as the current one.

$ git checkout bugfix
now switches to the named branch.

$ git reset -q COMMITNR

This moves the current revision of the current branch (it is 'bugfix' to a older revision. COMMITNR is the hash number of any commit, see git log

$ git checkout .

resynchronized all files of the selected revision.

...changing any files and

$ git commit

builds a side branch in the repository (archive).

Now a switch to another branch and its revision is possible in the same sandbox to work with it:

$ git checkout master

now switches back to this named branch and resynchronizes all files. Work with it, commit etc.

If there should be worked only at one side branch to any time, and be worked at another side branch to another time, then only one sandbox is necessary. You can switch between the branches. The files are changed, all files are stored in the git archive.

If there should be worked with more as one side branches to the same time, a copy of the git archive is necessary. The archive and the files should be stored at different places on the hard disk, or at more as one computer etc. It isn't recommended to use the same git archive, may be with an symbolic link in linux. The disadvantage is: The git archive knows the current branch, which was selected with 'checkout'. If you want to use only one archive but more as one sandbox for the files, you can have a symbolic link in the sandboxes to the same archive. But then you have to switch between the side-branches before any status, commit etc. action are done in one of the sandboxes. But be attentive to your files. You may overwrite they if you are careless. You can't do that at the same time, maybe more as one people in network. It will be confused if they are work concurrently.

I haven't test yet, but it shouldn't a problem to merge the more as one git archives without conflicts, if only one archive has changed only one side branch.

[[Image:git-side-branch-example.png|example side branches in git]]

'''Now back to bazaar''':

John A Meinel proposed the following answer:

If you want to commit new changes based on an older revision, you generally want to start a new branch. So something like

bzr branch master feature -r OLD
cd feature
bzr commit

If you are using a checkout you can do

cd checkout
bzr branch --switch -r OLD ../master ../feature

TODO test

Bazaar-Notes

Admin — Fri, 22 Jul 2011 20:42:14 GMT

Admin: /* Side branches */

@ident=Bazaar_notes

Links:
* [[Bazaar-guide]]: a guide to use Bazaar.

This size is in german, because it is discussed in a german team. It will be presented in english in the future. TODO

==Kurzer Abriss, Arbeit mit MKSSI, git, mercurial, Bazaar==

Hartmut: MKSSI ist seit über 10 Jahren bei mir in Gebrauch.
* Nur auf Arbeit, zentrale Administration,
* Die MKSSI-Software wird normalerweise nicht ständig updated. Das Arbeiten ist nicht sehr schnell, eher etwas für ordentliche Pflege.
* Wird gemacht, für die Versionen, die herausgegeben werden. Nicht für stündliche kleine Änderungen. Da wäre der Arbeitsaufwand zu hoch.

Hartmut: git war das erste der 'dritten Generation' für mich.
* Geht ganz gut, init commit, alles ganz einfach
* Nachschauen der Änderungen: Hier ist die GUI (gitk) nicht sehr bedienerfreundlich. Die schnelle Tastaturbedienung ist mangelhaft, der Tastaturfokus ist im falschen Teilfenster. Immer mit Maus schieben ...
* Linux-like cmdline-Bedienung auf Windows-PC ist für mich eher interessant.

Hartmut: mercurial - ähnlich wie git, nur eher für windows, eigentlich sehr ähnlich git.

Hartmut: Bazaar gefällt mir persönlich wegen der GUI besser.

Hartmut: Alle drei Systeme sind aber funktionell eher ähnlich. Ich pflege Quellen in Bazaar, um sie dann auch in hg zu committen, mit selbigem commit-Text wie in Bazaar zuvor zusammengestellt. Das ist nur ein Aufruf. Ein Hg-Archiv beispielsweise für CRuntimeJavalike liegt auf [[https://bitbucket.org/jchartmut/cruntimejavalike bitbucket.org/jchartmut/cruntimejavalike]]. Hg deshalb, weil die bitbucket-Seite nur hg unterstützt. Der Aufwand, in hg doppelt zu pflegen, ist kaum erhebenswert.

;Commit-Text zusammenstellen

:Vorderhand geht es beim Commit-text darum: Was leistet diese Version insgesamt, unterschied zur Vorversion. In der Zweiten Linie geht es aber um die Änderung in den einzelnen Files.

:Sind im Commit sehr viele Files enthalten, dann handelt es sich meist um das Ergebnis eines Refactoring wegen einer Änderung. Solche Änderungen brauchen in den Quellfiles nicht vermerkt werden, zuviel Aufwand, uninteressant.

:Sind dagegen wenige Files geändert, dann lag meist auch eine Änderung der Funktionalität vor. Diese sollte unabhängig vom Commit in den Quellfiles notiert werden. Hier hilft aber die Differenzanzeige, um während des Commit die Änderungen in den Files zu vermerken. Man kann einen passenden Commit-Text zusammenstellen, dabei die Änderung der Einzelfiles betrachten und dabei in den Einzelfiles Änderungen notieren (log des Files).

:Ein automatisches Eintragen der Änderung in den Files aus dem checkin-Textes aus der Arbeit mit dem Source-Integrity-System produziert meist Einträge in den Files, die die Änderungen schlecht abbilden. Das liegt daran, weil der Arbeitsaufwand für jeden Einzelfile zu hoch ist. Dieses automatische Eintragen ist aber eine häufig verwendete oder voreingestellte Methode bei MKSSI & co.

: Der Arbeitsaufwand bei manuellem Eintragen in den File ist deshalb bei Bazaar geringer, weil
:* Es gibt eine schnelle Übersicht, welche Files betroffen sind. Einfacher Knopfdruck für Viewdiff. Man kann schnell auswählen, bei welchen Files ggf. gleiche Einträge überhaupt notwendig sind. Nicht bei allen geänderten.
:* Mit den Files, die keine wesentlichen Änderungen enthalten sondern nur Anpassungen an Änderungen anderer Files, braucht man sich also gar nicht beschäftigen.
:* Die Änderung im File eingetragen und per Zwischenablage auch im Commit-Text abgelegt ist dann eigentlich nur einmaliger Aufwand, nicht zweimal.
:* Wenn es wesentliche Änderungen sind, dann ist die Beschreibung der Änderung auch ein schöpferischer und nicht formeller Akt. Dann lohnt es sich auch, die entsprechend notwendige Zeit aufzubringen. Möglicherweise wird man bei der Änderungsbeschreibung im File auch noch weitere dabei entdeckte Pflegekorrekturen anbringen, die insgesamt die Quelle weiter aufwerten. Dann hat es sich sowieso gelohnt.

==Source Content Management oder hart archivieren? Nur Quellen im SCM?==

Eine harte Archivierung ist das Verpacken der Files auf einem Datenträger. Da das Zip-format sich als langjährig beständig erwiesen hat, kann man ganze File-Bäume zippen und irgendwo aufheben.

Nachteil: Keine Unterstützung für Diff-View außer auspacken und mit einem Diff-tool vergleichen. Der Total-Commander eignet sich dazu allerdings recht gut, da er in beiden Paneelen in zip-Archive tief eintauchen kann.

Vorteil: Unabhängig von einem Tool, die Files einer Version sind zusammengebunden einfach da. Es hat sich schon oft als günstig erwiesen, lange Jahre zurückliegende Files nicht mit den damaligen Tools aufrollen zu müssen sondern einfach entzippen.

Der Vorteil für die Langjährigkeit sollte bedacht werden.

=>Schlussfolgerung: Ab und zu zippen und wegpacken, mindestens bei wichtigen Releaseständen. Aber unnütze zipfiles auch mal löschen.

=>Schlussfolgerung: Für akutelle Softwareentwicklung jedenfalls ein Source-Integrity-Tool nutzen, Zippen nur zusätzlich.

===Verzeichnissstuktur-Rückschluss===

Sowohl für das Zippen als auch für Sourcenpflege, Sourcenaustausch usw. liegt der tatsächliche Umfang von Sources insgesamt meist in einem Bereich von wenigen Megabyte. Damit ist der Datenaustausch mindestens erleichtert. Wenn man in die selbe Verzeichnisstruktur in der Quellen liegen noch hineintue:
* Objects
* erzeugte executable und umfangreiche Datenbasis-Files (Visual Studio ncb-Files und dergleichen)
* logfiles, Output-Files beim Testen
* alte Archive (zips)

dann springt der Umfang des Verzeichnisbausms von wenigen Megabyte ganz schnell auf -zig Megabyte. Das Problem merkt man
* beim zippen (ganz schnell mal ablegen zum späteren Vergleich)
* beim Vergleichen (alle Obj erscheinen als geändert, alles rot, erst mal schaun was das ist)
* bei der Pflege der Sources in einem SM-system (Source Management): viele nicht erfasste files: Sind die wichtig? Ach, sind nur Obj, doch ein wichtige wird übersehen.

=>Schlussfolgerung: Möglichst Sources von Testfiles und Executables trennen. Die wenigen Files, die nicht trennbar sind (weil die Tools sie ins aktuelle Verzeichnis legen), in einer ignore-Liste erfassen, ggf. beim zippen ausschließen usw. Sind es wenige, dann sind sie verwaltbar
* Object-Files auf einem tmp-Ordner speichern
* Generierergebnisse neben dem Source-Baum speichern.

===Archivieren von Executables===
Aus oben genannten Gründen sollten die Libs und Executables ''nicht'' mit den Sources im SM gemischt werden.
* Die libs und executables könnten einerseits immer aus den Sources generiert werden (wenn alles richtig ist)
* Die libs und executables sind nicht vergleichbar mit üblichen diffs.
* Die libs und executables sind im Code-Umfang zu hoch.

Es ist aber wichtig, libs und exe im Zusammenhang mit einem Checkpoint der Sources zu speichern.
* Als Auslieferungsstand
* Als wichtigen Teststand für Rückrüsten, möglicherweise ein Kandidat für Auslieferung.

Lösung:
* Beim committen eines guten Standes, der angetestet ist, ein kleines batch laufen lassen, das die exes lokal kopiert mit Datumskennzeichnung.
* Damit sind mehrere exes mit Datumsverbindung zum commit lokal vorhanden. Es kann getestet werden.
* '''Auslieferung: Executables und ggf. libs als zip abspeichern''',, siehe oben. Dabei auf den Stand zugreifen, der vorher lokal kopiert wurde und garantiert aus den Sources, die committed wurden, erstellt wurde.
* Nur bei '''Master-Releases''', die entgültig ausgeliefert werden, sollte folgeder Aufwand getrieben werden: Nach erfolgreichem Test die Quellen auf Produktgenerierungsrechner von anderer Person auschecken, neu compilieren, neues Generat erstellen und nochmals testen. Diese Vorgehensweise sichert die Konsistenz der Quellen mit dem Generat und dürfte bei Auslieferungen wichtig sein, dauert aber in der täglichen Fortschrittsarbeit einfach zu lange.

==Mehrere Repositories für ein Produkt==
@ident=multiBzr

;Produkt aus mehreren Quell-Komponenten

:Produkt (Executable etc.) besteht aus Quellen aus mehreren Projekten (Komponenten).
Die Quell-Komponenten sind relativ unabhängig und werden an anderer Stelle aus anderen Zusammenhängen ebenfalls gepflegt.

:Schlussfolgerung: Nicht mischen, weil sonst kein Durchblick wo was gepflegt wird.
Jede Quell-Komponente wird in ihrem eigenem .bzr-repository gepflegt.

;Quell-Komponenten befinden sich im Produkt-Sourcenbaum in jeweils bestimmten Unterverzeichnissen

:Unterverzeichnisordnung ist zweckmäßig, weil damit auch im Produkt-Verzeichnis ordnung herrscht.

:In linux kann dort ein symbolischer Link stehen, d.h. Quellen stehen eigentlich ganz woanders. In Windows ist eine Kopie der Komponenten-Quellen im Produkt-Verzeichnisbaum vorhanden.

: In windows kann aber auch ggf. eine Quellkomponente auch ganz woanders stehen, beispielsweise kann bei Eclipse ein Verzeichnis mit absolutem Pfad von irgendwo dem Projkekt hinzugefügt werden. Das ganze ist eine Sache von Pfaden, die irgendwo definiert sein müssen.

:Schlussfolgerung: Das .bzr-Repository der Quellen der Komponente sollte in dem Unterverzeichnis stehen.

: Folglich hängt der Name des Unterverzeichnisses nicht an der Quellkomponente, kann im Produkt auch beliebig gewählt werden. Folglich kann die Quellkomponente auch irgendwo anders stehen, also kein Unterverzeichnis sondern absoluter Pfad. Der absolute Pfad wird beim editieren/generieren beachtet.

Das spricht insgesamt dafür, ein Produkt aus mehreren Bazaar-Quell-Repositories zusammenzusetzen.

==Mehrere Produkte aus einem Repository==
Das große Thema ist Wiederverwendung (Reuse). Häufig zu Beobachten: Reuse besteht aus copy'n paste and change. Die Quellen wandern also irgendwo anders hin, bzgl SCM auch für den einzelnen besser zu beherrschen - man muss sich nur mit dem beschäftigen, was man selbst hat.

Das ist keine wirkliche Wiederverwendung. Der wirkliche Vorteil des reuse geht dabei verloren:
* Fehler, die in Produkten festgestellt werden, werden in den jeweiligen Modulen korrigiert und sind dann automatisch auch für andere Produkte mit korrigiert, obwohl sie dort ggf. noch gar nicht aufgefallen sind.

Für true-reuse ist es notwendig, die Software-Module so zu bauen, dass sie '''unverändert''' in verschiedenen Produkten verwendbar sind und das Änderungen für alle Produkte nutzbar sind. Das ist eine Frage der Schnittstellen. Die Schnittstellen sind viel wichtiger als die innere Funktionalität. Letztere kann man immer noch verbessern. Schnittstellenänderungen sind kritisch. - Andererseits sind Schnittstellenänderungen auch verträglich, wenn sie formell adaptiert werden können.

Ein shared-Repository in bazaar scheint die Lösung zu bieten, aus einem recht großen Quellenumfang für verschiedene Komponenten verschiedene Quellen herauslösen zu können. Die Komponenten haben selbe gemeinsame Quellen, ggf. in verschiedenen Revisionen, die aber immer abgeglichen werden können sollten. Die Komponenten sind dann Basis für ein Produkt. Komponenten existieren in Form von libs oder jars in Java und können eigenständig getestet werden:

Quellen Komponenten Produkte
viele ===> weniger ===> aus Komponenten
verschiedene überschaubar und Produkt-spezial-Quellen
gebaut.

Wie funktioniert shared-Repository als zentraler Bezug - bin beim testen. (Hartmut)
==Zentrale Ablage für Repositories==
@ident=centralRepos

Man kann immer und überall Repositories haben. Behält man den überblick und synchronisiert diese gegenseitig (push, pull), dann gibt es auch nicht zuviele Seitenzweige.

Jedoch, arbeiten viele Leute mit den Repositories, auch weniger eingeweihte, einfache Nutzer, anderes Problem Archivierung, langjähriges aufheben: Dann sollte an einer definierten Stelle das Master-Repository stehen. Jeder Quellenbearbeiter hat die Pflicht, sich mit dem Master-Repository abzustimmen, also seine Änderungen zu pushen oder von dort zu pullen. Gegebenenfalls sollte eine Person mit der Pflege des Master-Repositories beauftragt sein. Mindestens bei Releaseständen muss diese Person dort bereinigend eingreifen.

===Creating one shared repository in the local space===
The ''local space'' means any external hard disk, network folder or such which is owned by one person, by me. It is my local space, which can be used from some more people in my direct environment.

For any component of sources one shared repository should be created one time. On one sub directory per component: ''bzre: Bazaar -> Start -> Initialize: (x) Shared repository''. An existing plain branch can be pushed to them.

===Creating a branch for working===

* Create a new plain branch at the working position: ''bzre: Bazaar -> Start -> Initialize: (x) Plain branch''.
* Pull from a shared repositiory: ''Button Pull, select the shared repository, select a branch.
** If there are some files already, create the branch at a new position and then move .bzr subdir.

==Branches und dessen Auflösung==
@ident=.branch

;Viele Seitenzweige wegen unterschiedlichen Korrekturen

:Man kann sich auf den Standpunkt stellen, bei Korrekturen für kundenrelevante Software jeweils nur das aufgetretene Fehlerbild zu behandeln, alle anderen Softwareteile unverändert zu lassen. (''Do not touch a running system''). Das ist eine weit verbreitete Vorgehensweise. Folge sind dann sehr viele Seitezweige, die kaum mehr zusammenfließen.

: Primär ist diese Vorgehensweise richtig.

: Es zeigt sich aber, dass eine Änderung in Quellen, auch Restrukturierung, häufig zwar Nacharbeiten erforderlich macht. Diese Nacharbeiten sind aber formal abhandelbar. Man braucht nicht an jeder Stelle einer notwendigen Adaption an geänderte Quellenstände nachzudenken sondern muss nur den Compiler befragen. Kommt keine Fehlermeldung, ist alles in Ordnung. Eine Fehlermeldung soll mit formellen anschauen von Aufrufargumenttypen usw. behebbar sein, ohne dass man in die eigentliche Funktionalität einsteigt. Ist eine solche Nacharbeit möglich, dann kostet diese nur die Zeit der Pflege der Quellen, keine extra Testzeit. Zudem kann die Quellenpflege von jemanden ausgeführt werden, der zwar sehr gute Kenntnisse von Quellen und COmpiler hat, aber keine Tiefenkenntnis für die jeweilige Anwendung haben braucht. Man kann also delegieren.

: In diesem Sinn ist eine Adaption eines Produktes an veränderte Quellen der Komponenten möglich und zweckmäßig. Mann kann dann eher an einem Hauptzweig arbeiten.

: Schlussfolgerung: Schnelle Änderungen ->Seitenzweig, Auflösen dessen, Änderung in Hauptzweig einfließen lassen und Adaption des Produktes auf Hautpzweig der Komponenten ausführen.

===Side branches===
less experience

bzr checkout ../masterlocation . -r REVNR

Gets a part of trunk untio REVNR. It is similar

bzr revert -r REVNR

What is the difference???

bzr update ../masterlocation .

This copies all files in the current dir. It seems to destroy the older-revision side branch (?)

Is there a possibility to checkin changes based on a older revision, without any merge. Only the changed files based on the older revision should be stored in the bazaar repositiory - to compare with other versions or look for changes later. Background: Changing of some source files to bugfix an older software. The reason is not develop and merge.

The workflow of develop and bugfix in a decentralized team is explained in
* [[http://doc.bazaar.canonical.com/latest/en/user-guide/organizing_branches.html doc.bazaar.canonical.com/latest/en/user-guide/organizing_branches]].

But this is not the problem of side branches, more the problem of development in team.

'''An side glance to git''':

$ git branch bugfix

creates a branch named 'bugfix' in the same only one repository. It is a branch with the same revision as the current one.

$ git checkout bugfix
now switches to the named branch.

$ git reset -q COMMITNR

This moves the current revision of the current branch (it is 'bugfix' to a older revision. COMMITNR is the hash number of any commit, see git log

$ git checkout .

resynchronized all files of the selected revision.

...changing any files and

$ git commit

builds a side branch in the repository (archive).

Now a switch to another branch and its revision is possible in the same sandbox to work with it:

$ git checkout master

now switches back to this named branch and resynchronizes all files. Work with it, commit etc.

If there should be worked only at one side branch to any time, and be worked at another side branch to another time, then only one sandbox is necessary. You can switch between the branches. The files are changed, all files are stored in the git archive.

If there should be worked with more as one side branches to the same time, a copy of the git archive is necessary. The archive and the files should be stored at different places on the hard disk, or at more as one computer etc. It isn't recommended to use the same git archive, may be with an symbolic link in linux. The disadvantage is: The git archive knows the current branch, which was selected with 'checkout'. If you want to use only one archive but more as one sandbox for the files, you can have a symbolic link in the sandboxes to the same archive. But then you have to switch between the side-branches before any status, commit etc. action are done in one of the sandboxes. But be attentive to your files. You may overwrite they if you are careless. You can't do that at the same time, maybe more as one people in network. It will be confused if they are work concurrently.

I haven't test yet, but it shouldn't a problem to merge the more as one git archives without conflicts, if only one archive has changed only one side branch.

[[Img:http://www.vishia.org/SwEng/pictures/git-side-branch-example.jpg|example side branches in git]]

'''Now back to bazaar''':

John A Meinel proposed the following answer:

If you want to commit new changes based on an older revision, you generally want to start a new branch. So something like

bzr branch master feature -r OLD
cd feature
bzr commit

If you are using a checkout you can do

cd checkout
bzr branch --switch -r OLD ../master ../feature

TODO test

Components of CRuntimeJavalike

Admin — Tue, 19 Jul 2011 22:21:17 GMT

Admin: hint to embedded usage

==Navigation==
* up: [[Main_Page]] / [[Component]]
* down: see chapters

==Overview==
'''CRuntimeJavalike''' is a tree of C-files proper to use in '''embedded applications'''. All files are written by Hartmut Schorrig, www.vishia.org. They are used in some applications in profession too (with second license model). It is a conglomeration of different things, of course. It contains some makefiles to build libraries for a PC platform.

The CRuntimeJavalike can be used in any application, especially for embedded systems. It contains a OSAL-layer, which is provided for Windows and Linux. The OSAL-layer have to be adapted for other operation systems. Some adaption exists and are tested and used in profession. With adapting the OSAL-layer the sources can be used and the examples can run on any platform.

==Distribution and sources in internet==

* distribution: [[http://sf.net/projects/java2c sf.net/projects/java2c]] The CRuntimeJavalike is distributed as part of the Java2C-Translator. But it can be used without this translator too. Download the distribution and use only the CRuntimeJavalike. [[http://sf.net/projects/zbnf sf.net/projects/zbnf]]
* bazaar-archive on [[https://launchpad.net/jc/trunk launchpad.net/jc]]
* description, home-site on [[http://www.vishia.org/Jc www.vishia.org/Jc]]

==OSAL==
See [[OSAL]]. The OSAL-component contains
* C-files, which are special written for the appropriate operation system.
* One Headerfile, which contains some depending definitions which should be adapted to the platform, os and compiler. It is the [[os_types_def]].h.
* Headerfiles, which are independent of the operation system. It describes the OSAL-interface.
* Headerfiles, which contains simple C-definitions and declarations. It are independent of compiler, platform and os.
** [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_Exception.h.html include/Fwc/fw_Exception.h]]: Exception handling for C and C++ inclusive Stacktrace-Mechanism. In C a longjmp is used to throw. (longjmp.h is defined in the old Standards of C and in C99 too).
** [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_Formatter.h.html include/Fwc/fw_Formatter.h]]: Declaration of methods for formatting Strings. It include time-formattings. It is similar to sprintf.
** [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_MemC.h.html include/Fwc/fw_MemC.h]]: Definition of a struct MemC with pointer and its size. Some macros to handle with pointer. Some function prototypes for MemC-handling.
** [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_Readline.h.html include/Fwc/fw_Readline.h]]: Support of reading lines from a file. A line can be terminated with 0d, 0a or any combination (Windows, Unix, Mac-conventions all in one). The os_file.h is used as interface to read a file.
** [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_SimpleC.h.html include/Fwc/fw_SimpleC.h]]: Some basicly simple macros and function declarations.
** [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_String.h.html include/Fwc/fw_String.h]]: Basic functions for String storing in a struct StringJc. It is the alternative to zero-terminated C-Strings. The pointer and the length is stored. The basic functions are a bridge between 0-terminated C-strings and StringJc-referenced strings.
** [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_ThreadContext.h.html include/Fwc/fw_ThreadContext.h]]: The ThreadContext is managed in the OSAL, but its struct is defined here.
** [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_timeconversions.h.html include/Fwc/fw_timeconversions.h]]: struct and funtion declarations for time conversions: A timestamp should be stored internally in form of currently seconds and microseconds after a start time. The conversion to a human readable time should be done only for presentation. The routines support the conversion.
** [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_Va_list.h.html include/Fwc/fw_Va_list.h]]: An appreciation to the < stdarg.h> concept. The value as new: Any argument-type of a variable argument list is described with one char in a char*-string with one char. With the knowledge of the correct type any users function can be use the variable argument more correctly. Usual any other information should be necessary, for example the format-String of sprintf. This header and functions are used in fw_formatter.h

* C-files, which contains common sources for OSAL
* C-files, which contains common sources for simple C-functions. It can be used in the OSAL-Adaption.

With this Sources a application can be written os-indenpendent. All this sources are independent of the Java2C-thinking. This sources are not complex. There are not any assumption to Java.

SourceLinesAndDocu

Admin — Tue, 19 Jul 2011 22:08:44 GMT

Admin:

==Navigation==
* up: [[Main_Page]]
* down basics: TODO

==Overview==

Lines of code are many lines - only the developer of them looks through it. Or?

Sources have a structure. It is the formal syntax of the language primary. Code lines are top-down structures of classes, data-struct, methods, statement blocks. They can be analyzed formally and presented in there structure. Modern programming environments do so.

==Advantage of textual source lines in comparison with graphic programming==

* '''Code lines - change tracking''': Older and newer versions of sources are able to compare. All source version systems support that. It is possible to track which functionality is changed why, when, who and what exactly.

* ''Graphical programming - change tracking''': If there is a textual representation of the graphical appearance, it is possible to track changes line code lines too. Only it is another notation. But some graphic programming systems stores there content in special maybe binary files or a database adequate form, which doesn't allow a simple comparison of content.

* '''Code lines - searching anything''': Because they are textual files, a grep or ordinary search of text can be applied. Sometimes any textual hint is given to search the proper line. For example there is a textual sequence in an error message or a label on a button - search it in code lines of all files and you find the line where it is handled, without knowledge and understanding of the whole structure of the software.

* ''Graphical programming - searching anything''': It may be a search function in the graphical programming environment. Is it proper to use?

Summary: Code lines are better to handle but graphic programming is better to understand. Use a graphical programming environment with a simple representation of its content in code lines.

==Generating documentation from code lines==

* The code lines are the first (hack first ideas) and last (debug errors, implement features) which are touched by the programmer. Some programmers don't like writing documentation.

* Documentation outside of the code doesn't seem to be actual. Is it corrected in progress with the code changing?

===javadoc - Java source documentation===

javadoc is a generator to produce html-pages from Java sources. It is a part of any standard Java developer kit.

* The appearance of the code is the same worldwide. It is a standard. Anybody Java developer knows it.
* The writing styles of comments in the sources are the same worldwide. Anybody Java developer writes with the same style guides.
* Writing comments for javadoc style is supported by tools, for example in eclipse.

* An example produced with javadoc from me: [[http://www.vishia.org/Java/docuSrcJavaPublic/org/vishia/java2C/LocalIdents.html LocalIdents.java]]
* An example with graphical content. The source file is used only as base for documentation. [[http://www.vishia.org/Java/docuSrcJavaPublic/org/vishia/java2C/Docu.B_ProcessOfTranslation.html Docu.java]]
* An example from Sun/Oracle: [[http://download.oracle.com/javase/6/docs/api/java/lang/String.html String.java]]
* An example from apache: [[http://xerces.apache.org/xerces2-j/javadocs/api/org/w3c/dom/ls/DOMImplementationLS.html DOMImplementationLS.java]]

You can see - all styles of documentation are comparable. The kind of presentation of the functionality is equal.

In the html presentation you get the links to all types automatically without any effort in the source.

The thinking is:
* Comment the function and mission of any variable or association (pointer to other class or data struct).
* Comment the function and mission of any method. Write shortly what the method does.
* Write one sentence for core function and mission.
* Write some sentences for details.
* You can use lists using the html-known tags < ul>, < li> etc.
* You can write tables using < table> etc. But that is more complex.
* You can use html-links for example for images in the html presentation. In the code you see the name of the file (the link)
* You can use links to other elements of the source! It is written {@link class#method(paramtypes)}. Eclipse helps you while selecting with the usual write completion functionality.

The thinking of commenting influences the thinking to a good software structure and proper identifier. If you write the comment, you will think about the meaning of the code elements and you will correct it if it isn't proper.

===Doxygen===

[[http://www.stack.nl/~dimitri/doxygen/ doxygen]] is a usual documentation generation system used for C and C++ sources often. Doxygen has a lot of adjustment possibilities to control the kind of comment designation. It has a lot of possibilities to generate cross references of code and so on. Therefore it is more multifaceted.

===Using javadoc styles for C and C++ sources===

The javadoc notification style of comments in source code is widespread in most of sources. It is possible to use for doxygen too, if the doxygen control files are adjusted for that style. The basic write style is:

/**Comment core function in the first sentence.
* Some more information if necessary.*/
int x;

The comment is written before the element.

/**Comment core function in the first sentence.
* Some more information if necessary.
* A {@link OtherClass} in the explanation appears in a html-link
* for a proper navigation.
* <nowiki><ul><li></nowiki>Some remarks are proper able to read in lists.
* <nowiki><li></nowiki>next list bullet.
* <nowiki></ul></nowiki>
* @param par the explanation of the parameter
* @param par2 the next
* @return explanation what returns the method
* @throws IllegalArgumentException explanation of exceptions if there are any
*/
int myRoutine(int par, float par2);

You can write some elaborate explanation if necessary. But think about correction if the parameter of a method are changed or details of the functionality are changed.

==Generating an UML-Model from Headerfiles==

One of the disadvantage of code lines and documentation lines is: It has only one dimension, from to do down. If you have cross references to other code parts or chapter in a document, only links are able to use.

The advantage of [[http://en.wikipedia.org/wiki/Unified_Modeling_Language UML (Wikipedia) is:

* The relation between parts of a software are shown in 2 dimensions. It is in an area, not only in lines.

* There may be more as one presentation possible to show relations between the same software parts.

An representation of C software in form of UML diagrams is a good documentation.

Usual the direction of work is thought from the UML model to the code. It is ''automatic code generation''. It presumes, that a developer is more friendly with UML diagrams but with source lines.

But often programmers are more conversant in writing code lines. If some details of implementation should be regarded, the code lines are the nearest way to notify it. Therefore the generation of UML from code lines is proper too! It is similar to generate documentation from code lines.

===XMI and UML repository===

The [[http://en.wikipedia.org/wiki/XML_Metadata_Interchange XMI (Wikipedia)]]-Format is the data-interchanging format for UML. It is standardized for all UML tools.

A '''''repository''''' is the database for all UML diagrams managed in a UML tool.

The repository can be represented in the XMI format. The converter from C headerfiles to UML converts header files to a XMI-format-repository. The XMI file can be inputted in a UML tool. Then diagrams can be created with this given database using a UML tool.

===Tools to generate XMI from header files===

The converter contained in the download [[http://sourceforge.net/projects/zbnf ZBNF (sourceforge)]] parses headerfiles and then generates an XMI-file.
The download contains a folder <tt>zbnfjax</tt> which should be copied to a proper location on the local harddisk. This folder contains all jar files (Java archives) and scripts to work. Additional there are necessary
* [[http://saxon.sourceforge.net/ SAXON XSLT translator (sourceforge)]]
* [[http://www.jdom.org/ jdom]]
This software tools should be downloaded and placed on the hard disk too.

On a linux system I have copied it to

/usr/share/XML_Tools/
-rwxrwxr-x 1 root root 153253 13. Feb 2008 jdom.jar
drwxr-xr-x 7 root root 4096 12. Mär 2010 org.apache.ant_1.6.5
-rwxrwxr-x 1 root root 5468048 22. Okt 2009 saxon9he.jar
-rwxrwxr-x 1 root root 5046534 28. Okt 2009 saxon9.jar
-rwxrwxr-x 1 root root 37139 28. Okt 2009 saxon9-jdom.jar

/usr/share/vishia/
lrwxrwxrwx 1 root root 50 3. Jul 05:41 zbnfjax

/usr/bin/
-rwxr-xr-x 1 root root 76 3. Jul 05:41 zbnfjax

The last file is the start script for all zbnf commands. It is placed in the systems PATH because the translation is invoked using

>zbnfjax options

as line command.

On windows it is adequate. The tools are the same.

SourceLinesAndDocu

Admin — Tue, 19 Jul 2011 21:22:12 GMT

Admin: javadoc

SourceLinesAndDocu

Admin — Tue, 19 Jul 2011 20:27:10 GMT

Admin: Protected "SourceLinesAndDocu" ([edit=autoconfirmed] (indefinite) [move=autoconfirmed] (indefinite))

SourceLinesAndDocu

Admin — Mon, 18 Jul 2011 19:41:56 GMT

Admin: Advantage of textual source lines in comparison with graphic programming - some ideas.

GraphicAndCodeGen

Admin — Mon, 18 Jul 2011 19:23:26 GMT

Admin: overview

==Navigation==
* up: [[Main_Page]]
* down basics: TODO

==Overview==
Programming with graphical support is the 4-th level of high-level programming languages. UML is one of the graphical languages.

Other ''languages'' are Simulink, Simplorer and such those graphical environments for controlling.

A user can use that graphic languages without knowledge of detailed thinks of source code programming. It is an important advantage. A user can consider the own problems, not the problems of implementation.

The graphical languages should described the structures of connections of blocks etc. in netlists or such adequate. Using that connection lists a line source code can be generated which regards some conditions of deployment of the target platform. The C-language should be the first choosing, because the C language is the usual base language for all platforms.

The generated C-sources should be able to read and understand by a usual C programmer, but they shouldn't be adapted and corrected to introduce implementation details. It is similar to list files to view an assembler code which is compiled from C- sources. It may be able to view and understand but never changed.

Main Page

Admin — Mon, 18 Jul 2011 19:08:50 GMT

Admin: /* Java4C */

This site holds information about programming for embedded software in an ObjectOriented style. Ideas and concepts of the Java programming language are integrated in this thinks. Some articles describe software-engineering-topics.

==Base links==
* [[Java4C]] - why Java-thinking and Java-using for the C-programming
* [[CRuntimeJavalike]] - A base library for embedded C-software
* [[Java2C]] - A translator from Java-sources to C-sources
* [[Component]] - Building the application with components and moduls
* [[Bazaar]] - A Source Version System

==Java4C==
* [[Java4C]] - why Java-thinking and Java-using for the C-programming
* [[SourceLinesAndDocu]] - Graphic programming (UML or other) or '''lines of code''' - what is with the documentation
* [[GraphicAndCodeGen]] - Graphical programming and code generation

==CRuntimeJavalike==
* [[CRuntimeJavalike]] - A base library for embedded C-software
===OSAL===
* [[OSAL]] - The interface to the operation system with its application layer
* basics: [[os_types_def]] // [[os_AtomicAccess]] // [[os_error]]
* somethings: [[os_mem]] // [[os_time]] // [[os_file]] // [[os_endian]]
* MultiThreading: [[os_thread]] -- [[os_waitnotify]] -- [[os_sync]] -- [[os_socket]]
* [[os_Shared_Memory]] -- [[Dual port RAM]] -- [[InterProcessCommunication]]
* [[os_driver]] operation access at driver level

==Java2C==
* [[http://www.vishia.org/Java2C www.vishia.org/Java2C]]
* [[http://sourceforge.net/projects/java2c Java2C on sourceforge]]

==Components, Dependencies==
* [[Component]] - Building the application with components and modules - common description

===Components of vishia-Software===
* [[Components of vishia-Java]] - presentation of components from all Java - sources of org/vishia
* [[Components of CRuntimeJavalike]] - presentation of components from C-sources

===Dependencies===
* [[Dependency]]

====Dependency-Topics of C====
* [[forward declaration of struct]]
* [[forward declaration of functions in header]]

====Dependency-Topics of ObjectOrientation (Java, C)====

* TODO

==Bazaar==
* [[Bazaar]] - A Source Version System
* [[Bazaar-Notes]]: discussion (german) about Source-Management and directory structures

==Linux==
* [[Linux]] - Some hints for Linux usage

==The key author of this site==

has experience in embedded programming since 1977, beginning with Assembler programming with the Z80-processor. I'm working for a company in germany in themes of embedded control. This site presents experiences independently of concretely job definitions. Hartmut Schorrig, [[http://www.vishia.org www.vishia.org]]

==The mission of this site - Your contribution==

Exchange of experiences. You can take place on discussion. You can complement the text of the pages with your experience and knowledge. You can improve the appearance of the text.

It is necessary to register with a user name to this site.

Future: [[Inspector datagram]]

Bazaar-Notes

Admin — Fri, 15 Jul 2011 16:40:04 GMT

Admin: side branches to commit changes for bugfixes, how to work

@ident=Bazaar_notes

Links:
* [[Bazaar-guide]]: a guide to use Bazaar.

This size is in german, because it is discussed in a german team. It will be presented in english in the future. TODO

==Kurzer Abriss, Arbeit mit MKSSI, git, mercurial, Bazaar==

Hartmut: MKSSI ist seit über 10 Jahren bei mir in Gebrauch.
* Nur auf Arbeit, zentrale Administration,
* Die MKSSI-Software wird normalerweise nicht ständig updated. Das Arbeiten ist nicht sehr schnell, eher etwas für ordentliche Pflege.
* Wird gemacht, für die Versionen, die herausgegeben werden. Nicht für stündliche kleine Änderungen. Da wäre der Arbeitsaufwand zu hoch.

Hartmut: git war das erste der 'dritten Generation' für mich.
* Geht ganz gut, init commit, alles ganz einfach
* Nachschauen der Änderungen: Hier ist die GUI (gitk) nicht sehr bedienerfreundlich. Die schnelle Tastaturbedienung ist mangelhaft, der Tastaturfokus ist im falschen Teilfenster. Immer mit Maus schieben ...
* Linux-like cmdline-Bedienung auf Windows-PC ist für mich eher interessant.

Hartmut: mercurial - ähnlich wie git, nur eher für windows, eigentlich sehr ähnlich git.

Hartmut: Bazaar gefällt mir persönlich wegen der GUI besser.

Hartmut: Alle drei Systeme sind aber funktionell eher ähnlich. Ich pflege Quellen in Bazaar, um sie dann auch in hg zu committen, mit selbigem commit-Text wie in Bazaar zuvor zusammengestellt. Das ist nur ein Aufruf. Ein Hg-Archiv beispielsweise für CRuntimeJavalike liegt auf [[https://bitbucket.org/jchartmut/cruntimejavalike bitbucket.org/jchartmut/cruntimejavalike]]. Hg deshalb, weil die bitbucket-Seite nur hg unterstützt. Der Aufwand, in hg doppelt zu pflegen, ist kaum erhebenswert.

;Commit-Text zusammenstellen

:Vorderhand geht es beim Commit-text darum: Was leistet diese Version insgesamt, unterschied zur Vorversion. In der Zweiten Linie geht es aber um die Änderung in den einzelnen Files.

:Sind im Commit sehr viele Files enthalten, dann handelt es sich meist um das Ergebnis eines Refactoring wegen einer Änderung. Solche Änderungen brauchen in den Quellfiles nicht vermerkt werden, zuviel Aufwand, uninteressant.

:Sind dagegen wenige Files geändert, dann lag meist auch eine Änderung der Funktionalität vor. Diese sollte unabhängig vom Commit in den Quellfiles notiert werden. Hier hilft aber die Differenzanzeige, um während des Commit die Änderungen in den Files zu vermerken. Man kann einen passenden Commit-Text zusammenstellen, dabei die Änderung der Einzelfiles betrachten und dabei in den Einzelfiles Änderungen notieren (log des Files).

:Ein automatisches Eintragen der Änderung in den Files aus dem checkin-Textes aus der Arbeit mit dem Source-Integrity-System produziert meist Einträge in den Files, die die Änderungen schlecht abbilden. Das liegt daran, weil der Arbeitsaufwand für jeden Einzelfile zu hoch ist. Dieses automatische Eintragen ist aber eine häufig verwendete oder voreingestellte Methode bei MKSSI & co.

: Der Arbeitsaufwand bei manuellem Eintragen in den File ist deshalb bei Bazaar geringer, weil
:* Es gibt eine schnelle Übersicht, welche Files betroffen sind. Einfacher Knopfdruck für Viewdiff. Man kann schnell auswählen, bei welchen Files ggf. gleiche Einträge überhaupt notwendig sind. Nicht bei allen geänderten.
:* Mit den Files, die keine wesentlichen Änderungen enthalten sondern nur Anpassungen an Änderungen anderer Files, braucht man sich also gar nicht beschäftigen.
:* Die Änderung im File eingetragen und per Zwischenablage auch im Commit-Text abgelegt ist dann eigentlich nur einmaliger Aufwand, nicht zweimal.
:* Wenn es wesentliche Änderungen sind, dann ist die Beschreibung der Änderung auch ein schöpferischer und nicht formeller Akt. Dann lohnt es sich auch, die entsprechend notwendige Zeit aufzubringen. Möglicherweise wird man bei der Änderungsbeschreibung im File auch noch weitere dabei entdeckte Pflegekorrekturen anbringen, die insgesamt die Quelle weiter aufwerten. Dann hat es sich sowieso gelohnt.

==Source Content Management oder hart archivieren? Nur Quellen im SCM?==

Eine harte Archivierung ist das Verpacken der Files auf einem Datenträger. Da das Zip-format sich als langjährig beständig erwiesen hat, kann man ganze File-Bäume zippen und irgendwo aufheben.

Nachteil: Keine Unterstützung für Diff-View außer auspacken und mit einem Diff-tool vergleichen. Der Total-Commander eignet sich dazu allerdings recht gut, da er in beiden Paneelen in zip-Archive tief eintauchen kann.

Vorteil: Unabhängig von einem Tool, die Files einer Version sind zusammengebunden einfach da. Es hat sich schon oft als günstig erwiesen, lange Jahre zurückliegende Files nicht mit den damaligen Tools aufrollen zu müssen sondern einfach entzippen.

Der Vorteil für die Langjährigkeit sollte bedacht werden.

=>Schlussfolgerung: Ab und zu zippen und wegpacken, mindestens bei wichtigen Releaseständen. Aber unnütze zipfiles auch mal löschen.

=>Schlussfolgerung: Für akutelle Softwareentwicklung jedenfalls ein Source-Integrity-Tool nutzen, Zippen nur zusätzlich.

===Verzeichnissstuktur-Rückschluss===

Sowohl für das Zippen als auch für Sourcenpflege, Sourcenaustausch usw. liegt der tatsächliche Umfang von Sources insgesamt meist in einem Bereich von wenigen Megabyte. Damit ist der Datenaustausch mindestens erleichtert. Wenn man in die selbe Verzeichnisstruktur in der Quellen liegen noch hineintue:
* Objects
* erzeugte executable und umfangreiche Datenbasis-Files (Visual Studio ncb-Files und dergleichen)
* logfiles, Output-Files beim Testen
* alte Archive (zips)

dann springt der Umfang des Verzeichnisbausms von wenigen Megabyte ganz schnell auf -zig Megabyte. Das Problem merkt man
* beim zippen (ganz schnell mal ablegen zum späteren Vergleich)
* beim Vergleichen (alle Obj erscheinen als geändert, alles rot, erst mal schaun was das ist)
* bei der Pflege der Sources in einem SM-system (Source Management): viele nicht erfasste files: Sind die wichtig? Ach, sind nur Obj, doch ein wichtige wird übersehen.

=>Schlussfolgerung: Möglichst Sources von Testfiles und Executables trennen. Die wenigen Files, die nicht trennbar sind (weil die Tools sie ins aktuelle Verzeichnis legen), in einer ignore-Liste erfassen, ggf. beim zippen ausschließen usw. Sind es wenige, dann sind sie verwaltbar
* Object-Files auf einem tmp-Ordner speichern
* Generierergebnisse neben dem Source-Baum speichern.

===Archivieren von Executables===
Aus oben genannten Gründen sollten die Libs und Executables ''nicht'' mit den Sources im SM gemischt werden.
* Die libs und executables könnten einerseits immer aus den Sources generiert werden (wenn alles richtig ist)
* Die libs und executables sind nicht vergleichbar mit üblichen diffs.
* Die libs und executables sind im Code-Umfang zu hoch.

Es ist aber wichtig, libs und exe im Zusammenhang mit einem Checkpoint der Sources zu speichern.
* Als Auslieferungsstand
* Als wichtigen Teststand für Rückrüsten, möglicherweise ein Kandidat für Auslieferung.

Lösung:
* Beim committen eines guten Standes, der angetestet ist, ein kleines batch laufen lassen, das die exes lokal kopiert mit Datumskennzeichnung.
* Damit sind mehrere exes mit Datumsverbindung zum commit lokal vorhanden. Es kann getestet werden.
* '''Auslieferung: Executables und ggf. libs als zip abspeichern''',, siehe oben. Dabei auf den Stand zugreifen, der vorher lokal kopiert wurde und garantiert aus den Sources, die committed wurden, erstellt wurde.
* Nur bei '''Master-Releases''', die entgültig ausgeliefert werden, sollte folgeder Aufwand getrieben werden: Nach erfolgreichem Test die Quellen auf Produktgenerierungsrechner von anderer Person auschecken, neu compilieren, neues Generat erstellen und nochmals testen. Diese Vorgehensweise sichert die Konsistenz der Quellen mit dem Generat und dürfte bei Auslieferungen wichtig sein, dauert aber in der täglichen Fortschrittsarbeit einfach zu lange.

==Mehrere Repositories für ein Produkt==
@ident=multiBzr

;Produkt aus mehreren Quell-Komponenten

:Produkt (Executable etc.) besteht aus Quellen aus mehreren Projekten (Komponenten).
Die Quell-Komponenten sind relativ unabhängig und werden an anderer Stelle aus anderen Zusammenhängen ebenfalls gepflegt.

:Schlussfolgerung: Nicht mischen, weil sonst kein Durchblick wo was gepflegt wird.
Jede Quell-Komponente wird in ihrem eigenem .bzr-repository gepflegt.

;Quell-Komponenten befinden sich im Produkt-Sourcenbaum in jeweils bestimmten Unterverzeichnissen

:Unterverzeichnisordnung ist zweckmäßig, weil damit auch im Produkt-Verzeichnis ordnung herrscht.

:In linux kann dort ein symbolischer Link stehen, d.h. Quellen stehen eigentlich ganz woanders. In Windows ist eine Kopie der Komponenten-Quellen im Produkt-Verzeichnisbaum vorhanden.

: In windows kann aber auch ggf. eine Quellkomponente auch ganz woanders stehen, beispielsweise kann bei Eclipse ein Verzeichnis mit absolutem Pfad von irgendwo dem Projkekt hinzugefügt werden. Das ganze ist eine Sache von Pfaden, die irgendwo definiert sein müssen.

:Schlussfolgerung: Das .bzr-Repository der Quellen der Komponente sollte in dem Unterverzeichnis stehen.

: Folglich hängt der Name des Unterverzeichnisses nicht an der Quellkomponente, kann im Produkt auch beliebig gewählt werden. Folglich kann die Quellkomponente auch irgendwo anders stehen, also kein Unterverzeichnis sondern absoluter Pfad. Der absolute Pfad wird beim editieren/generieren beachtet.

Das spricht insgesamt dafür, ein Produkt aus mehreren Bazaar-Quell-Repositories zusammenzusetzen.

==Mehrere Produkte aus einem Repository==
Das große Thema ist Wiederverwendung (Reuse). Häufig zu Beobachten: Reuse besteht aus copy'n paste and change. Die Quellen wandern also irgendwo anders hin, bzgl SCM auch für den einzelnen besser zu beherrschen - man muss sich nur mit dem beschäftigen, was man selbst hat.

Das ist keine wirkliche Wiederverwendung. Der wirkliche Vorteil des reuse geht dabei verloren:
* Fehler, die in Produkten festgestellt werden, werden in den jeweiligen Modulen korrigiert und sind dann automatisch auch für andere Produkte mit korrigiert, obwohl sie dort ggf. noch gar nicht aufgefallen sind.

Für true-reuse ist es notwendig, die Software-Module so zu bauen, dass sie '''unverändert''' in verschiedenen Produkten verwendbar sind und das Änderungen für alle Produkte nutzbar sind. Das ist eine Frage der Schnittstellen. Die Schnittstellen sind viel wichtiger als die innere Funktionalität. Letztere kann man immer noch verbessern. Schnittstellenänderungen sind kritisch. - Andererseits sind Schnittstellenänderungen auch verträglich, wenn sie formell adaptiert werden können.

Ein shared-Repository in bazaar scheint die Lösung zu bieten, aus einem recht großen Quellenumfang für verschiedene Komponenten verschiedene Quellen herauslösen zu können. Die Komponenten haben selbe gemeinsame Quellen, ggf. in verschiedenen Revisionen, die aber immer abgeglichen werden können sollten. Die Komponenten sind dann Basis für ein Produkt. Komponenten existieren in Form von libs oder jars in Java und können eigenständig getestet werden:

Quellen Komponenten Produkte
viele ===> weniger ===> aus Komponenten
verschiedene überschaubar und Produkt-spezial-Quellen
gebaut.

Wie funktioniert shared-Repository als zentraler Bezug - bin beim testen. (Hartmut)
==Zentrale Ablage für Repositories==
@ident=centralRepos

Man kann immer und überall Repositories haben. Behält man den überblick und synchronisiert diese gegenseitig (push, pull), dann gibt es auch nicht zuviele Seitenzweige.

Jedoch, arbeiten viele Leute mit den Repositories, auch weniger eingeweihte, einfache Nutzer, anderes Problem Archivierung, langjähriges aufheben: Dann sollte an einer definierten Stelle das Master-Repository stehen. Jeder Quellenbearbeiter hat die Pflicht, sich mit dem Master-Repository abzustimmen, also seine Änderungen zu pushen oder von dort zu pullen. Gegebenenfalls sollte eine Person mit der Pflege des Master-Repositories beauftragt sein. Mindestens bei Releaseständen muss diese Person dort bereinigend eingreifen.

===Creating one shared repository in the local space===
The ''local space'' means any external hard disk, network folder or such which is owned by one person, by me. It is my local space, which can be used from some more people in my direct environment.

For any component of sources one shared repository should be created one time. On one sub directory per component: ''bzre: Bazaar -> Start -> Initialize: (x) Shared repository''. An existing plain branch can be pushed to them.

===Creating a branch for working===

* Create a new plain branch at the working position: ''bzre: Bazaar -> Start -> Initialize: (x) Plain branch''.
* Pull from a shared repositiory: ''Button Pull, select the shared repository, select a branch.
** If there are some files already, create the branch at a new position and then move .bzr subdir.

==Branches und dessen Auflösung==
@ident=.branch

;Viele Seitenzweige wegen unterschiedlichen Korrekturen

:Man kann sich auf den Standpunkt stellen, bei Korrekturen für kundenrelevante Software jeweils nur das aufgetretene Fehlerbild zu behandeln, alle anderen Softwareteile unverändert zu lassen. (''Do not touch a running system''). Das ist eine weit verbreitete Vorgehensweise. Folge sind dann sehr viele Seitezweige, die kaum mehr zusammenfließen.

: Primär ist diese Vorgehensweise richtig.

: Es zeigt sich aber, dass eine Änderung in Quellen, auch Restrukturierung, häufig zwar Nacharbeiten erforderlich macht. Diese Nacharbeiten sind aber formal abhandelbar. Man braucht nicht an jeder Stelle einer notwendigen Adaption an geänderte Quellenstände nachzudenken sondern muss nur den Compiler befragen. Kommt keine Fehlermeldung, ist alles in Ordnung. Eine Fehlermeldung soll mit formellen anschauen von Aufrufargumenttypen usw. behebbar sein, ohne dass man in die eigentliche Funktionalität einsteigt. Ist eine solche Nacharbeit möglich, dann kostet diese nur die Zeit der Pflege der Quellen, keine extra Testzeit. Zudem kann die Quellenpflege von jemanden ausgeführt werden, der zwar sehr gute Kenntnisse von Quellen und COmpiler hat, aber keine Tiefenkenntnis für die jeweilige Anwendung haben braucht. Man kann also delegieren.

: In diesem Sinn ist eine Adaption eines Produktes an veränderte Quellen der Komponenten möglich und zweckmäßig. Mann kann dann eher an einem Hauptzweig arbeiten.

: Schlussfolgerung: Schnelle Änderungen ->Seitenzweig, Auflösen dessen, Änderung in Hauptzweig einfließen lassen und Adaption des Produktes auf Hautpzweig der Komponenten ausführen.

===Side branches===
less experience

bzr checkout ../masterlocation . -r REVNR

Gets a part of trunk untio REVNR. It is similar

bzr revert -r REVNR

What is the difference???

bzr update ../masterlocation .

This copies all files in the current dir. It seems to destroy the older-revision side branch (?)

Is there a possibility to checkin changes based on a older revision, without any merge. Only the changed files based on the older revision should be stored in the bazaar repositiory - to compare with other versions or look for changes later. Background: Changing of some source files to bugfix an older software. The reason is not develop and merge.

Os error

Admin — Fri, 03 Jun 2011 19:56:00 GMT

Admin: starting text

==Navigation==
* up: [[OSAL]] // [[Main_Page]]
* siblings: [[os_types_def]] // [[os_AtomicAccess]] // [[os_mem]] // [[os_time]] // [[os_file]] // [[os_endian]]
* MultiThreading: [[os_thread]] -- [[os_waitnotify]] -- [[os_sync]] -- [[os_socket]]
* [[os_Shared_Memory]] -- [[Dual port RAM]] -- [[InterProcessCommunication]]
* [[os_driver]] operation access at driver level

==Overview==

Generally an error handling is necessary to detect failures in the software. In a situation where a function doesn't know what to do
*either it should return with an message ''error''
*or it should call an error routine
*or it should throw an exception.

In the first case the user should be check the return state and handle with the error, whereby in the last two cases the user should not know anything about possible errors in its ''best case programming branch''. Therefore a try-catch-throw mechanism is established for high level user programming. But in the OSAL layer usual a return value is used to detect the error state. It is so, because any try-catch mechanism is defined in a layer above the OSALs one only.

Nevertheless it is advisable to support an error handling adequate to try-throw at OSAL-level too.

==Error handling in OSAL==

The OSAL in the CRuntimeJavalike environment supports the following mechanism:

===Error routine to user level support===
A function type

C_TYPE typedef void MT_os_Error(int errorCode, const char* description, int value1, int value2);

is defined. The routine

extern_C int os_setErrorRoutine(MT_os_Error* routine);

accepts any routine with this prototype. Using this mechanism any error at OSAL level can be transferred to a higher user level, for example to use a throw mechanism in a try-catch environment or to support an error logging.

All conflicts in the OSAL adaption routines with the operation system or with itself should call the routine ...TODO

OSAL

Admin — Fri, 13 May 2011 07:10:41 GMT

Admin: Common headers: Fwc

==Navigation==
* up: [[Main_Page]]
* down basics: [[os_types_def]] // [[os_AtomicAccess]] // [[os_error]]
* somethings: [[os_mem]] // [[os_time]] // [[os_file]] // [[os_endian]]
* MultiThreading: [[os_thread]] -- [[os_waitnotify]] -- [[os_sync]] -- [[os_socket]]
* [[os_Shared_Memory]] -- [[Dual port RAM]] -- [[InterProcessCommunication]]
* [[os_driver]] operation access at driver level

==Overview==
@ident=OSAL

'''OS-independent programming'''

Some programmers work for their ''project''. It may be running on a special hardware with a special
operation system, mostly a RTOS (Real Time Operation System).
The tests are executed at the target hardware - reality tests.
Thus the thought is ''C is not C, any target system needs its own slang (dialect)''.

What is missing? Compilation of the sources with a proper Integrated Development Environment (IDE).
On the PCs, there are some good IDEs, such as Eclipse, Microsoft Visual Studio etc.
Mostly, the IDEs for a special hardware are good, but not so good like PC-platform-tools.

What is also missing? Functional testing the algorithm. It isn't a real-time test. But
it may be essential.

What is the effort? The algorithm in C need to compile in a PC-environment. It should be able to test,
not in real-time, maybe only in one thread or more.
For this reason the OS-functionality should be able to use at the test-environment.

What is the result:
* Well functional tested algorithms
* Faster writing, reorganization, optimizing and gardening of sources, because the PC-platform
is able to use for faster work.
* Better sources.

The tests on the target-platform are reduced to test the real platform problems, not to test the algorithm basically.

'''Need of special Operation System capabilities'''

Most of the Operation Systems are similar in a large way of thinking. All of these support multi-threading,
with mutex etc. Most of them have a file system in a adequate kind etc.

The differences are: They should be support the hardware platform with different processors, different
equipment in RAM, ROM, different I/O. But the user programming shouldn't consider all of them so far.
The user programming should be realized in a more abstract shell. This means the RTOS should be proper
for the hardware, but it should not have to much special features for the user programming. It may be
useful only for driver or interrupt-level-programming.

Conclusion: The user programming should use unified interfaces to the operation system.

==OSAL-Level in the CRuntimeJavalike==

Programming in Java is OS-independent in the first way. In that mind, the CRuntimeJavalike needs a
''Operation System Adaption Level'' (OSAL).

The given OSAL is layered closed to a ''not-only Java-like''-programming. It supports standard C
functionality. The typical Java-like functions like ThreadJc based on this OSAL-interface.

A first idea in the past was to introduce the OSAL-level in the OS-oriented classes like ThreadJc, ObjectJc
with its ''synchronized_ObjectJc''-methods etc. But a Java-independent definition
of the OSAL-interface provides some use-cases for the non-java-like-oriented programming, too.
So it is implemented independently from Java-like-C-classes.

==Simple-C in OSAL==

The OSAL-component contains Headerfiles and Implementations, which contain simple C-functionality. They are independent of compiler, platform and operation systems. That header are contained in the CRuntimeJavalike-package (see [[https://launchpad.net/zbnf/srcjava.zbnf launchpad.net/zbnf/srcjava.zbnf]]) in the subdir include/Fwc/*.h:

* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_Exception.h.html include/Fwc/fw_Exception.h]]: Exception handling for C and C++ inclusive Stacktrace-Mechanism. In C a longjmp is used to throw. (longjmp.h is defined in the old Standards of C and in C99 too).
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_Formatter.h.html include/Fwc/fw_Formatter.h]]: Declaration of methods for formatting Strings. It include time-formattings. It is similar to sprintf.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_MemC.h.html include/Fwc/fw_MemC.h]]: Definition of a struct MemC with pointer and its size. Some macros to handle with pointer. Some function prototypes for MemC-handling.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_Readline.h.html include/Fwc/fw_Readline.h]]: Support of reading lines from a file. A line can be terminated with 0d, 0a or any combination (Windows, Unix, Mac-conventions all in one). The os_file.h is used as interface to read a file.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_SimpleC.h.html include/Fwc/fw_SimpleC.h]]: Some basicly simple macros and function declarations.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_String.h.html include/Fwc/fw_String.h]]: Basic functions for String storing in a struct StringJc. It is the alternative to zero-terminated C-Strings. The pointer and the length is stored. The basic functions are a bridge between 0-terminated C-strings and StringJc-referenced strings.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_ThreadContext.h.html include/Fwc/fw_ThreadContext.h]]: The ThreadContext is managed in the OSAL, but its struct is defined here.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_timeconversions.h.html include/Fwc/fw_timeconversions.h]]: struct and funtion declarations for time conversions: A timestamp should be stored internally in form of currently seconds and microseconds after a start time. The conversion to a human readable time should be done only for presentation. The routines support the conversion.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_Va_list.h.html include/Fwc/fw_Va_list.h]]: An appreciation to the < stdarg.h> concept. The value as new: Any argument-type of a variable argument list is described with one char in a char*-string with one char. With the knowledge of the correct type any users function can be use the variable argument more correctly. Usual any other information should be necessary, for example the format-String of sprintf. This header and functions are used in fw_formatter.h

The C-files are named adequate to the header files. They are located in the same component CRuntimeJavalike in the directory <tt>source/Fwc</tt>. This base routines can be used for implementation of special os-adaption. Nevertheless for example the exception handling should not be used for the osal-level, because usage of exception handling is a decision of applications. It is offered here, but not used. The OSAL-adaption should be written simple and easy.

==Common headers==

The os-adaption contain C-files, which are special written for the appropriate operation system. But the headerfiles are identical over all mostly. It describes the OSAL-interface.

An interface in C-language is established in header-files. Most of compiler-tool-associated header-files
declare the same things, but in their own files in a maybe different form. So the risk of
little differences are given.

Instead all OS-interface-functions should be declared in the same header-files, independent of
the current used operation system. The implementation of the OSAL should use this files and adapt
their OS-functions.

All of those OS-independent common header files for OSAL-functions are declared
in the folder <tt>CRuntimeJavalike/OSAL/inc</tt>. The current file list is:

os_types_def_common.h
os_mem.h
os_endian.h
os_error.h
os_AtomicAccess.h
os_time.h
os_thread.h
os_sync.h
os_file.h
os_socket.h

The OSAL-Implementation can use some basicly C-routines, which are offered for common usage with a OSAL-library too. That headers files are contained in <tt>CRuntimeJavalike/Fwc</tt>:

fw_SimpleC.h
fw_MemC.h
fw_String.h
fw_Formatter.h
fw_timeconversions.h
fw_ThreadContext.h
fw_Exception.h
fw_Va_list.h
fw_Readline.h

==Different headers==

* One Headerfile, which contains some depending definitions which should be adapted to the platform, os and compiler. It is the [[os_types_def]].h.
Some things should be declared or defined in a OS-specific way. The same things should be defined
in a different kind, appropriate to the operation system and the compiler properties.

The most important file doing this is the ,,os_types_def.h,,. The same file-name is used
in different directories, all specific for OS and compiler. It defines the same things in a different way.

The most noticeable property is the definition of the OS- and compiler-depending definition of
fix-size-integer types. The C99-standard suggests the usage of ,,int32_t,, etc. But most of the
programmers had created their own standard before or simultaneous to the C99-Standard. These types are present
in many sources. They are defined in some special headers like ,,standard.h,,,
which is anytime ,,mystandard.h,,. These types are defined in the ,,os_types_def.h,,.

There are some things defined there in addition:
* little/big endian defines, processors are different.
* C++-keyword for C-usage, especially ,,bool,,, ,,true,,, ,,false,,.
* The macro METHOD_C which maybe ,,extern "C",, or not.
* A ,,MemUnit,,-type. It is the type which describes one element in the address spaces.
It is not a ,,char,, anytime, not in Signal-processors.

==C-basics==

There are some things, which may defined in a good C-design able to use for the OSAL-level too.
This C-basics are provided OS-independently in the following files (definition and implementation):

fw_Exception.h
fw_Exception.c
fw_LogMessage.h
fw_LogMessage.c
fw_Va_list.h
fw_formatter.c
fw_Formatter.h
fw_SimpleC.c
fw_SimpleC.h
fw_MemC.h
fw_MemC.c
objectBaseC.h
fw_Object.c
fw_timeconversions.h
fw_timeconversions.c
fw_ThreadContext.h
fw_String.h
fw_threadContext.c

This so-named ''framework''-level is independent from the OSAL-adaption and it is ready to use
for the OS-adaption.

==OS-adaption for threads==

see ,,os_thread.h,,

OSAL

Admin — Fri, 13 May 2011 06:31:57 GMT

Admin: /* Common headers */

==Navigation==
* up: [[Main_Page]]
* down basics: [[os_types_def]] // [[os_AtomicAccess]] // [[os_error]]
* somethings: [[os_mem]] // [[os_time]] // [[os_file]] // [[os_endian]]
* MultiThreading: [[os_thread]] -- [[os_waitnotify]] -- [[os_sync]] -- [[os_socket]]
* [[os_Shared_Memory]] -- [[Dual port RAM]] -- [[InterProcessCommunication]]
* [[os_driver]] operation access at driver level

==Overview==
@ident=OSAL

'''OS-independent programming'''

Some programmers work for their ''project''. It may be running on a special hardware with a special
operation system, mostly a RTOS (Real Time Operation System).
The tests are executed at the target hardware - reality tests.
Thus the thought is ''C is not C, any target system needs its own slang (dialect)''.

What is missing? Compilation of the sources with a proper Integrated Development Environment (IDE).
On the PCs, there are some good IDEs, such as Eclipse, Microsoft Visual Studio etc.
Mostly, the IDEs for a special hardware are good, but not so good like PC-platform-tools.

What is also missing? Functional testing the algorithm. It isn't a real-time test. But
it may be essential.

What is the effort? The algorithm in C need to compile in a PC-environment. It should be able to test,
not in real-time, maybe only in one thread or more.
For this reason the OS-functionality should be able to use at the test-environment.

What is the result:
* Well functional tested algorithms
* Faster writing, reorganization, optimizing and gardening of sources, because the PC-platform
is able to use for faster work.
* Better sources.

The tests on the target-platform are reduced to test the real platform problems, not to test the algorithm basically.

'''Need of special Operation System capabilities'''

Most of the Operation Systems are similar in a large way of thinking. All of these support multi-threading,
with mutex etc. Most of them have a file system in a adequate kind etc.

The differences are: They should be support the hardware platform with different processors, different
equipment in RAM, ROM, different I/O. But the user programming shouldn't consider all of them so far.
The user programming should be realized in a more abstract shell. This means the RTOS should be proper
for the hardware, but it should not have to much special features for the user programming. It may be
useful only for driver or interrupt-level-programming.

Conclusion: The user programming should use unified interfaces to the operation system.

==OSAL-Level in the CRuntimeJavalike==

Programming in Java is OS-independent in the first way. In that mind, the CRuntimeJavalike needs a
''Operation System Adaption Level'' (OSAL).

The given OSAL is layered closed to a ''not-only Java-like''-programming. It supports standard C
functionality. The typical Java-like functions like ThreadJc based on this OSAL-interface.

A first idea in the past was to introduce the OSAL-level in the OS-oriented classes like ThreadJc, ObjectJc
with its ''synchronized_ObjectJc''-methods etc. But a Java-independent definition
of the OSAL-interface provides some use-cases for the non-java-like-oriented programming, too.
So it is implemented independently from Java-like-C-classes.

==Simple-C in OSAL==

The OSAL-component contains Headerfiles and Implementations, which contain simple C-functionality. They are independent of compiler, platform and operation systems. That header are contained in the CRuntimeJavalike-package (see [[https://launchpad.net/zbnf/srcjava.zbnf launchpad.net/zbnf/srcjava.zbnf]]) in the subdir include/Fwc/*.h:

* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_Exception.h.html include/Fwc/fw_Exception.h]]: Exception handling for C and C++ inclusive Stacktrace-Mechanism. In C a longjmp is used to throw. (longjmp.h is defined in the old Standards of C and in C99 too).
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_Formatter.h.html include/Fwc/fw_Formatter.h]]: Declaration of methods for formatting Strings. It include time-formattings. It is similar to sprintf.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_MemC.h.html include/Fwc/fw_MemC.h]]: Definition of a struct MemC with pointer and its size. Some macros to handle with pointer. Some function prototypes for MemC-handling.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_Readline.h.html include/Fwc/fw_Readline.h]]: Support of reading lines from a file. A line can be terminated with 0d, 0a or any combination (Windows, Unix, Mac-conventions all in one). The os_file.h is used as interface to read a file.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_SimpleC.h.html include/Fwc/fw_SimpleC.h]]: Some basicly simple macros and function declarations.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_String.h.html include/Fwc/fw_String.h]]: Basic functions for String storing in a struct StringJc. It is the alternative to zero-terminated C-Strings. The pointer and the length is stored. The basic functions are a bridge between 0-terminated C-strings and StringJc-referenced strings.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_ThreadContext.h.html include/Fwc/fw_ThreadContext.h]]: The ThreadContext is managed in the OSAL, but its struct is defined here.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_timeconversions.h.html include/Fwc/fw_timeconversions.h]]: struct and funtion declarations for time conversions: A timestamp should be stored internally in form of currently seconds and microseconds after a start time. The conversion to a human readable time should be done only for presentation. The routines support the conversion.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_Va_list.h.html include/Fwc/fw_Va_list.h]]: An appreciation to the < stdarg.h> concept. The value as new: Any argument-type of a variable argument list is described with one char in a char*-string with one char. With the knowledge of the correct type any users function can be use the variable argument more correctly. Usual any other information should be necessary, for example the format-String of sprintf. This header and functions are used in fw_formatter.h

The C-files are named adequate to the header files. They are located in the same component CRuntimeJavalike in the directory <tt>source/Fwc</tt>. This base routines can be used for implementation of special os-adaption. Nevertheless for example the exception handling should not be used for the osal-level, because usage of exception handling is a decision of applications. It is offered here, but not used. The OSAL-adaption should be written simple and easy.

==Common headers==

The os-adaption contain C-files, which are special written for the appropriate operation system. But the headerfiles are identical over all mostly. It describes the OSAL-interface.

An interface in C-language is established in header-files. Most of compiler-tool-associated header-files
declare the same things, but in their own files in a maybe different form. So the risk of
little differences are given.

Instead all OS-interface-functions should be declared in the same header-files, independent of
the current used operation system. The implementation of the OSAL should use this files and adapt
their OS-functions.

All of those OS-independent common header files are declared
in the folder ,,CRuntimeJavalike/OSAL/inc,,. The current file list is:

os_types_def_common.h
os_mem.h
os_endian.h
os_error.h
os_AtomicAccess.h
os_time.h
os_thread.h
os_sync.h
os_file.h
os_socket.h

==Different headers==

* One Headerfile, which contains some depending definitions which should be adapted to the platform, os and compiler. It is the [[os_types_def]].h.
Some things should be declared or defined in a OS-specific way. The same things should be defined
in a different kind, appropriate to the operation system and the compiler properties.

The most important file doing this is the ,,os_types_def.h,,. The same file-name is used
in different directories, all specific for OS and compiler. It defines the same things in a different way.

The most noticeable property is the definition of the OS- and compiler-depending definition of
fix-size-integer types. The C99-standard suggests the usage of ,,int32_t,, etc. But most of the
programmers had created their own standard before or simultaneous to the C99-Standard. These types are present
in many sources. They are defined in some special headers like ,,standard.h,,,
which is anytime ,,mystandard.h,,. These types are defined in the ,,os_types_def.h,,.

There are some things defined there in addition:
* little/big endian defines, processors are different.
* C++-keyword for C-usage, especially ,,bool,,, ,,true,,, ,,false,,.
* The macro METHOD_C which maybe ,,extern "C",, or not.
* A ,,MemUnit,,-type. It is the type which describes one element in the address spaces.
It is not a ,,char,, anytime, not in Signal-processors.

==C-basics==

There are some things, which may defined in a good C-design able to use for the OSAL-level too.
This C-basics are provided OS-independently in the following files (definition and implementation):

fw_Exception.h
fw_Exception.c
fw_LogMessage.h
fw_LogMessage.c
fw_Va_list.h
fw_formatter.c
fw_Formatter.h
fw_SimpleC.c
fw_SimpleC.h
fw_MemC.h
fw_MemC.c
objectBaseC.h
fw_Object.c
fw_timeconversions.h
fw_timeconversions.c
fw_ThreadContext.h
fw_String.h
fw_threadContext.c

This so-named ''framework''-level is independent from the OSAL-adaption and it is ready to use
for the OS-adaption.

==OS-adaption for threads==

see ,,os_thread.h,,

Samba

Admin — Thu, 21 Apr 2011 20:59:47 GMT

Admin: Created page with '==Samba== Used with Suse 11.3 The following informations for a share are set Option Value * Only then a net use from a windows PC with another login works: guest ok Ye…'

==Samba==
Used with Suse 11.3

The following informations for a share are set
Option Value
* Only then a net use from a windows PC with another login works:
guest ok Yes
* Without that entry the user was 'nobody' if files are copied to linux.
force user hartmut
* ok
readonly No
path /home/hartmut
* I don't know what is it:
inherit acls No

Linux

Admin — Thu, 21 Apr 2011 20:53:39 GMT

Admin: Created page with 'My experience and hints for Linux * Samba'

My experience and hints for Linux
* [[Samba]]

Main Page

Admin — Thu, 21 Apr 2011 20:52:47 GMT

Admin:

This site holds information about programming for embedded software in an ObjectOriented style. Ideas and concepts of the Java programming language are integrated in this thinks. Some articles describe software-engineering-topics.

==Base links==
* [[Java4C]] - why Java-thinking and Java-using for the C-programming
* [[CRuntimeJavalike]] - A base library for embedded C-software
* [[Java2C]] - A translator from Java-sources to C-sources
* [[Component]] - Building the application with components and moduls
* [[Bazaar]] - A Source Version System

==Java4C==
* [[Java4C]] - why Java-thinking and Java-using for the C-programming

==CRuntimeJavalike==
* [[CRuntimeJavalike]] - A base library for embedded C-software
===OSAL===
* [[OSAL]] - The interface to the operation system with its application layer
* basics: [[os_types_def]] // [[os_AtomicAccess]] // [[os_error]]
* somethings: [[os_mem]] // [[os_time]] // [[os_file]] // [[os_endian]]
* MultiThreading: [[os_thread]] -- [[os_waitnotify]] -- [[os_sync]] -- [[os_socket]]
* [[os_Shared_Memory]] -- [[Dual port RAM]] -- [[InterProcessCommunication]]
* [[os_driver]] operation access at driver level

==Java2C==
* [[http://www.vishia.org/Java2C www.vishia.org/Java2C]]
* [[http://sourceforge.net/projects/java2c Java2C on sourceforge]]

==Components, Dependencies==
* [[Component]] - Building the application with components and modules - common description

===Components of vishia-Software===
* [[Components of vishia-Java]] - presentation of components from all Java - sources of org/vishia
* [[Components of CRuntimeJavalike]] - presentation of components from C-sources

===Dependencies===
* [[Dependency]]

====Dependency-Topics of C====
* [[forward declaration of struct]]
* [[forward declaration of functions in header]]

====Dependency-Topics of ObjectOrientation (Java, C)====

* TODO

==Bazaar==
* [[Bazaar]] - A Source Version System
* [[Bazaar-Notes]]: discussion (german) about Source-Management and directory structures

==Linux==
* [[Linux]] - Some hints for Linux usage

==The key author of this site==

has experience in embedded programming since 1977, beginning with Assembler programming with the Z80-processor. I'm working for a company in germany in themes of embedded control. This site presents experiences independently of concretely job definitions. Hartmut Schorrig, [[http://www.vishia.org www.vishia.org]]

==The mission of this site - Your contribution==

Exchange of experiences. You can take place on discussion. You can complement the text of the pages with your experience and knowledge. You can improve the appearance of the text.

It is necessary to register with a user name to this site.

Future: [[Inspector datagram]]

OSAL

Admin — Sun, 10 Apr 2011 03:06:35 GMT

Admin: /* Simple-C in OSAL */

==Navigation==
* up: [[Main_Page]]
* down basics: [[os_types_def]] // [[os_AtomicAccess]] // [[os_error]]
* somethings: [[os_mem]] // [[os_time]] // [[os_file]] // [[os_endian]]
* MultiThreading: [[os_thread]] -- [[os_waitnotify]] -- [[os_sync]] -- [[os_socket]]
* [[os_Shared_Memory]] -- [[Dual port RAM]] -- [[InterProcessCommunication]]
* [[os_driver]] operation access at driver level

==Overview==
@ident=OSAL

'''OS-independent programming'''

Some programmers work for their ''project''. It may be running on a special hardware with a special
operation system, mostly a RTOS (Real Time Operation System).
The tests are executed at the target hardware - reality tests.
Thus the thought is ''C is not C, any target system needs its own slang (dialect)''.

What is missing? Compilation of the sources with a proper Integrated Development Environment (IDE).
On the PCs, there are some good IDEs, such as Eclipse, Microsoft Visual Studio etc.
Mostly, the IDEs for a special hardware are good, but not so good like PC-platform-tools.

What is also missing? Functional testing the algorithm. It isn't a real-time test. But
it may be essential.

What is the effort? The algorithm in C need to compile in a PC-environment. It should be able to test,
not in real-time, maybe only in one thread or more.
For this reason the OS-functionality should be able to use at the test-environment.

What is the result:
* Well functional tested algorithms
* Faster writing, reorganization, optimizing and gardening of sources, because the PC-platform
is able to use for faster work.
* Better sources.

The tests on the target-platform are reduced to test the real platform problems, not to test the algorithm basically.

'''Need of special Operation System capabilities'''

Most of the Operation Systems are similar in a large way of thinking. All of these support multi-threading,
with mutex etc. Most of them have a file system in a adequate kind etc.

The differences are: They should be support the hardware platform with different processors, different
equipment in RAM, ROM, different I/O. But the user programming shouldn't consider all of them so far.
The user programming should be realized in a more abstract shell. This means the RTOS should be proper
for the hardware, but it should not have to much special features for the user programming. It may be
useful only for driver or interrupt-level-programming.

Conclusion: The user programming should use unified interfaces to the operation system.

==OSAL-Level in the CRuntimeJavalike==

Programming in Java is OS-independent in the first way. In that mind, the CRuntimeJavalike needs a
''Operation System Adaption Level'' (OSAL).

The given OSAL is layered closed to a ''not-only Java-like''-programming. It supports standard C
functionality. The typical Java-like functions like ThreadJc based on this OSAL-interface.

A first idea in the past was to introduce the OSAL-level in the OS-oriented classes like ThreadJc, ObjectJc
with its ''synchronized_ObjectJc''-methods etc. But a Java-independent definition
of the OSAL-interface provides some use-cases for the non-java-like-oriented programming, too.
So it is implemented independently from Java-like-C-classes.

==Simple-C in OSAL==

The OSAL-component contains Headerfiles and Implementations, which contain simple C-functionality. They are independent of compiler, platform and operation systems. That header are contained in the CRuntimeJavalike-package (see [[https://launchpad.net/zbnf/srcjava.zbnf launchpad.net/zbnf/srcjava.zbnf]]) in the subdir include/Fwc/*.h:

* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_Exception.h.html include/Fwc/fw_Exception.h]]: Exception handling for C and C++ inclusive Stacktrace-Mechanism. In C a longjmp is used to throw. (longjmp.h is defined in the old Standards of C and in C99 too).
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_Formatter.h.html include/Fwc/fw_Formatter.h]]: Declaration of methods for formatting Strings. It include time-formattings. It is similar to sprintf.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_MemC.h.html include/Fwc/fw_MemC.h]]: Definition of a struct MemC with pointer and its size. Some macros to handle with pointer. Some function prototypes for MemC-handling.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_Readline.h.html include/Fwc/fw_Readline.h]]: Support of reading lines from a file. A line can be terminated with 0d, 0a or any combination (Windows, Unix, Mac-conventions all in one). The os_file.h is used as interface to read a file.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_SimpleC.h.html include/Fwc/fw_SimpleC.h]]: Some basicly simple macros and function declarations.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_String.h.html include/Fwc/fw_String.h]]: Basic functions for String storing in a struct StringJc. It is the alternative to zero-terminated C-Strings. The pointer and the length is stored. The basic functions are a bridge between 0-terminated C-strings and StringJc-referenced strings.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_ThreadContext.h.html include/Fwc/fw_ThreadContext.h]]: The ThreadContext is managed in the OSAL, but its struct is defined here.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_timeconversions.h.html include/Fwc/fw_timeconversions.h]]: struct and funtion declarations for time conversions: A timestamp should be stored internally in form of currently seconds and microseconds after a start time. The conversion to a human readable time should be done only for presentation. The routines support the conversion.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_Va_list.h.html include/Fwc/fw_Va_list.h]]: An appreciation to the < stdarg.h> concept. The value as new: Any argument-type of a variable argument list is described with one char in a char*-string with one char. With the knowledge of the correct type any users function can be use the variable argument more correctly. Usual any other information should be necessary, for example the format-String of sprintf. This header and functions are used in fw_formatter.h

The C-files are named adequate to the header files. They are located in the same component CRuntimeJavalike in the directory <tt>source/Fwc</tt>. This base routines can be used for implementation of special os-adaption. Nevertheless for example the exception handling should not be used for the osal-level, because usage of exception handling is a decision of applications. It is offered here, but not used. The OSAL-adaption should be written simple and easy.

==Common headers==

The os-adaption contain C-files, which are special written for the appropriate operation system. But the headerfiles are identical over all mostly. It describes the OSAL-interface.

An interface in C-language is established in header-files. Most of compiler-tool-associated header-files
declare the same things, but in their own files in a maybe different form. So the risk of
little differences are given.

Instead all OS-interface-functions should be declared in the same header-files, independent of
the current used operation system. The implementation of the OSAL should use this files and adapt
their OS-functions.

All of those OS-independent common header files are declared
in the folder ,,CRuntimeJavalike/OSAL/inc,,. The current file list is:

os_adapter.h
os_endian.h
os_file.h.bak
os_mem.h
os_serror.h
os_socket.h
os_sync.h
os_time.h.bak
os_waitnotify.h
os_error.h
os_file.h
os_thread.h
os_AtomicAccess.h
os_time.h

==Different headers==

* One Headerfile, which contains some depending definitions which should be adapted to the platform, os and compiler. It is the [[os_types_def]].h.
Some things should be declared or defined in a OS-specific way. The same things should be defined
in a different kind, appropriate to the operation system and the compiler properties.

The most important file doing this is the ,,os_types_def.h,,. The same file-name is used
in different directories, all specific for OS and compiler. It defines the same things in a different way.

The most noticeable property is the definition of the OS- and compiler-depending definition of
fix-size-integer types. The C99-standard suggests the usage of ,,int32_t,, etc. But most of the
programmers had created their own standard before or simultaneous to the C99-Standard. These types are present
in many sources. They are defined in some special headers like ,,standard.h,,,
which is anytime ,,mystandard.h,,. These types are defined in the ,,os_types_def.h,,.

There are some things defined there in addition:
* little/big endian defines, processors are different.
* C++-keyword for C-usage, especially ,,bool,,, ,,true,,, ,,false,,.
* The macro METHOD_C which maybe ,,extern "C",, or not.
* A ,,MemUnit,,-type. It is the type which describes one element in the address spaces.
It is not a ,,char,, anytime, not in Signal-processors.

==C-basics==

There are some things, which may defined in a good C-design able to use for the OSAL-level too.
This C-basics are provided OS-independently in the following files (definition and implementation):

fw_Exception.h
fw_Exception.c
fw_LogMessage.h
fw_LogMessage.c
fw_Va_list.h
fw_formatter.c
fw_Formatter.h
fw_SimpleC.c
fw_SimpleC.h
fw_MemC.h
fw_MemC.c
objectBaseC.h
fw_Object.c
fw_timeconversions.h
fw_timeconversions.c
fw_ThreadContext.h
fw_String.h
fw_threadContext.c

This so-named ''framework''-level is independent from the OSAL-adaption and it is ready to use
for the OS-adaption.

==OS-adaption for threads==

see ,,os_thread.h,,

OSAL

Admin — Tue, 05 Apr 2011 16:51:45 GMT

Admin:

==Navigation==
* up: [[Main_Page]]
* down basics: [[os_types_def]] // [[os_AtomicAccess]] // [[os_error]]
* somethings: [[os_mem]] // [[os_time]] // [[os_file]] // [[os_endian]]
* MultiThreading: [[os_thread]] -- [[os_waitnotify]] -- [[os_sync]] -- [[os_socket]]
* [[os_Shared_Memory]] -- [[Dual port RAM]] -- [[InterProcessCommunication]]
* [[os_driver]] operation access at driver level

==Overview==
@ident=OSAL

'''OS-independent programming'''

Some programmers work for their ''project''. It may be running on a special hardware with a special
operation system, mostly a RTOS (Real Time Operation System).
The tests are executed at the target hardware - reality tests.
Thus the thought is ''C is not C, any target system needs its own slang (dialect)''.

What is missing? Compilation of the sources with a proper Integrated Development Environment (IDE).
On the PCs, there are some good IDEs, such as Eclipse, Microsoft Visual Studio etc.
Mostly, the IDEs for a special hardware are good, but not so good like PC-platform-tools.

What is also missing? Functional testing the algorithm. It isn't a real-time test. But
it may be essential.

What is the effort? The algorithm in C need to compile in a PC-environment. It should be able to test,
not in real-time, maybe only in one thread or more.
For this reason the OS-functionality should be able to use at the test-environment.

What is the result:
* Well functional tested algorithms
* Faster writing, reorganization, optimizing and gardening of sources, because the PC-platform
is able to use for faster work.
* Better sources.

The tests on the target-platform are reduced to test the real platform problems, not to test the algorithm basically.

'''Need of special Operation System capabilities'''

Most of the Operation Systems are similar in a large way of thinking. All of these support multi-threading,
with mutex etc. Most of them have a file system in a adequate kind etc.

The differences are: They should be support the hardware platform with different processors, different
equipment in RAM, ROM, different I/O. But the user programming shouldn't consider all of them so far.
The user programming should be realized in a more abstract shell. This means the RTOS should be proper
for the hardware, but it should not have to much special features for the user programming. It may be
useful only for driver or interrupt-level-programming.

Conclusion: The user programming should use unified interfaces to the operation system.

==OSAL-Level in the CRuntimeJavalike==

Programming in Java is OS-independent in the first way. In that mind, the CRuntimeJavalike needs a
''Operation System Adaption Level'' (OSAL).

The given OSAL is layered closed to a ''not-only Java-like''-programming. It supports standard C
functionality. The typical Java-like functions like ThreadJc based on this OSAL-interface.

A first idea in the past was to introduce the OSAL-level in the OS-oriented classes like ThreadJc, ObjectJc
with its ''synchronized_ObjectJc''-methods etc. But a Java-independent definition
of the OSAL-interface provides some use-cases for the non-java-like-oriented programming, too.
So it is implemented independently from Java-like-C-classes.

==Simple-C in OSAL==

The OSAL-component contains Headerfiles and Implementations, which contains simple C-functionality. It are independent of compiler, platform and operation systems. The header files are:

* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_Exception.h.html include/Fwc/fw_Exception.h]]: Exception handling for C and C++ inclusive Stacktrace-Mechanism. In C a longjmp is used to throw. (longjmp.h is defined in the old Standards of C and in C99 too).
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_Formatter.h.html include/Fwc/fw_Formatter.h]]: Declaration of methods for formatting Strings. It include time-formattings. It is similar to sprintf.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_MemC.h.html include/Fwc/fw_MemC.h]]: Definition of a struct MemC with pointer and its size. Some macros to handle with pointer. Some function prototypes for MemC-handling.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_Readline.h.html include/Fwc/fw_Readline.h]]: Support of reading lines from a file. A line can be terminated with 0d, 0a or any combination (Windows, Unix, Mac-conventions all in one). The os_file.h is used as interface to read a file.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_SimpleC.h.html include/Fwc/fw_SimpleC.h]]: Some basicly simple macros and function declarations.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_String.h.html include/Fwc/fw_String.h]]: Basic functions for String storing in a struct StringJc. It is the alternative to zero-terminated C-Strings. The pointer and the length is stored. The basic functions are a bridge between 0-terminated C-strings and StringJc-referenced strings.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_ThreadContext.h.html include/Fwc/fw_ThreadContext.h]]: The ThreadContext is managed in the OSAL, but its struct is defined here.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_timeconversions.h.html include/Fwc/fw_timeconversions.h]]: struct and funtion declarations for time conversions: A timestamp should be stored internally in form of currently seconds and microseconds after a start time. The conversion to a human readable time should be done only for presentation. The routines support the conversion.
* [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_Va_list.h.html include/Fwc/fw_Va_list.h]]: An appreciation to the < stdarg.h> concept. The value as new: Any argument-type of a variable argument list is described with one char in a char*-string with one char. With the knowledge of the correct type any users function can be use the variable argument more correctly. Usual any other information should be necessary, for example the format-String of sprintf. This header and functions are used in fw_formatter.h

The C-files are named adequate to the header files. This base routines can be used for implementation of special os-adaption. Nevertheless for example the exception handling should not be used for the osal-level, because usage of exception handling is a decision of applications. It is offered here, but not used.

==Common headers==

The os-adaption contain C-files, which are special written for the appropriate operation system. But the headerfiles are identical over all mostly. It describes the OSAL-interface.

An interface in C-language is established in header-files. Most of compiler-tool-associated header-files
declare the same things, but in their own files in a maybe different form. So the risk of
little differences are given.

Instead all OS-interface-functions should be declared in the same header-files, independent of
the current used operation system. The implementation of the OSAL should use this files and adapt
their OS-functions.

All of those OS-independent common header files are declared
in the folder ,,CRuntimeJavalike/OSAL/inc,,. The current file list is:

os_adapter.h
os_endian.h
os_file.h.bak
os_mem.h
os_serror.h
os_socket.h
os_sync.h
os_time.h.bak
os_waitnotify.h
os_error.h
os_file.h
os_thread.h
os_AtomicAccess.h
os_time.h

==Different headers==

* One Headerfile, which contains some depending definitions which should be adapted to the platform, os and compiler. It is the [[os_types_def]].h.
Some things should be declared or defined in a OS-specific way. The same things should be defined
in a different kind, appropriate to the operation system and the compiler properties.

The most important file doing this is the ,,os_types_def.h,,. The same file-name is used
in different directories, all specific for OS and compiler. It defines the same things in a different way.

The most noticeable property is the definition of the OS- and compiler-depending definition of
fix-size-integer types. The C99-standard suggests the usage of ,,int32_t,, etc. But most of the
programmers had created their own standard before or simultaneous to the C99-Standard. These types are present
in many sources. They are defined in some special headers like ,,standard.h,,,
which is anytime ,,mystandard.h,,. These types are defined in the ,,os_types_def.h,,.

There are some things defined there in addition:
* little/big endian defines, processors are different.
* C++-keyword for C-usage, especially ,,bool,,, ,,true,,, ,,false,,.
* The macro METHOD_C which maybe ,,extern "C",, or not.
* A ,,MemUnit,,-type. It is the type which describes one element in the address spaces.
It is not a ,,char,, anytime, not in Signal-processors.

==C-basics==

There are some things, which may defined in a good C-design able to use for the OSAL-level too.
This C-basics are provided OS-independently in the following files (definition and implementation):

fw_Exception.h
fw_Exception.c
fw_LogMessage.h
fw_LogMessage.c
fw_Va_list.h
fw_formatter.c
fw_Formatter.h
fw_SimpleC.c
fw_SimpleC.h
fw_MemC.h
fw_MemC.c
objectBaseC.h
fw_Object.c
fw_timeconversions.h
fw_timeconversions.c
fw_ThreadContext.h
fw_String.h
fw_threadContext.c

This so-named ''framework''-level is independent from the OSAL-adaption and it is ready to use
for the OS-adaption.

==OS-adaption for threads==

see ,,os_thread.h,,

Component

Admin — Mon, 21 Mar 2011 09:16:35 GMT

Admin:

==Navigation==
* up: [[Main_Page]]
* down: [[Components_of_vishia-Java]] [[Components_of_CRuntimeJavalike]]

==Components and modules, re-using==

A software should consist of more as one component. Each component should be able to describe, program and test independent of the application which uses it. A component may be able to use in several applications. Then it is reuseable.

Modules are the finer granularity inside components or inside the core of the application. Each module should be able to describe, program and test independently too. Modules may be one C/h-file or a package in Java or some related files.

A class in ObjectOrientation is the more finer granularity inside modules. A class in the C-programming is a logical coherence between one data structure and related subroutines. One class may be presented exactly with one source-file.

==Dependencies between components, modules, classes==

If another class is used inside a class, it depends on it. Formally it depends on the signature of the methods of the class. Really the functionality depends on the functionality of the called methods.

For a independent test of a class, module or component it may be necessary to abstract the functionality of the depending stuff. The behavior of the depending stuff should be replaced by a simulation or emulation.

===Dependencies defines components===

If a component need the presence of another component while compiling or linking, then the component depends on the other component formally. Components should be tailored to specified other components. If any other component is need only for a special function, which isn't the main stream functionality of the component, it is disagreeable. The user of the component should attend to the other component, which isn't need really. It is additional work to do without benefit.

Components can be depended on any common functions of a platform, which are present anytime. For example all base class of a Java Virtual Machine and its <tt>rt.jar</tt> library can be used in the Java-sources. Then the component may be designated as '''independent of any others'''.

If a component depends on another specified component, it builds a system of components. Such a component-system should not be complex. '''Dependency-breaker''' are need. The dependency breakers allow a formally translation (compilation) without the presence of other complex components. For running (linking), any incarnation of the ''components behind the dependency-breaker'' should be present. But that components may be replacements for simulation etc. if necessary.

===Dependencies in a application===

There are '''horizontal''' and '''vertical dependencies''': If a class/module/component can be created, described and tested independent on another class/module/component, it is deeper in vertical or parallel in horizontal layer. If a class/module/component needs another one, it is above that in vertical layer. ''It needs'' means, in the real application it is associated to it and calls some methods from there. For the independently test all needed classes/modules/components may be able to replace.

==Interfaces as dependency-breaker==

There is a problem: Module_A needs some methods from Module_B and on the other hand Module_B needs some things from Module_A. Both modules are parallel in layer, but there are not able to develop and test independently. - Either the both modules are not two separated modules, the functionality should be combined in one module. - Or it should be separated using interfaces.

Another Aspect of Interfaces: A Component should not need a special other component. It should be more commonly in its dependency-necessities. A selection of the other associated components should be possible, for example for simulation and real usage, for different platform necessities etc.

* While compiling only the interfaces should be present.
* While static linking in C/C++ or starting an application in Java or C++ with dynamic libraries any incarnation of interface-implementors can be used. Others for testing and for several application goals.
* A symbolic linkuage is possible: The selection of a dynamic library or implementation class can depend on the presence of a special library or jar-file in the file system. It is possible too to select a implementor by parametrizing, especially with a identifier string. In this kind selecting on runtime is possible.

===Interfaces in Java===

The ''interface'' is a language-element of Java. It defines methods with its signature, but without implementation. The description, "''what should the method do, which argument values are expectable, meaning of the return value''" belongs to the method anyway. In C++ interfaces are able to create in a similar kind as Java. It is a class with only virtual abstract methods and without any implementation:

class InterfaceExample { //C++-interface
virtual int aMethod(int arg) = 0;
};

====Selecting implementors while startup====

TODO

====Selecting implementors symbolic====

TODO Class.forName()

===Classic C - Headerfiles as interface===

The classic C programming knows headerfiles, which ones play the role of interfaces: Function prototypes has the same appearance as a method definition in a Java-interface or a virtual abstract methods:

extern int aFunction(int arg);

The difference to Java and C++-virtual-methods is: It is static linked. There can be only one implementation in a executable, whereby in Java and C++ the interface can be implement by several classes which are instantiated independently. It is a ''dynamic link''.

But the principle of dependency-break is the same.

===Classic C- struct forward declaration as dependency break===

In C and C++ there is a nice possibility to prevent to many include-necessities:

struct TheType_t;

typedef struct Example_t{
struct TheType_t* pointer;
} Example;

Inside the Example-struct a pointer of TheType is need. But <tt>TheType</tt> itself may left unknown. It isn't necessary to know the type while compiling this struct. It is not necessary to include the typedef of <tt>TheType</tt>

If the pointer is used in the implementation (the C-file), then the type should be known. The implementation-File includes the definition of:

typedef struct TheType_t{
int someStuff;
}Thetype;

Now the compiler checks the matching of <tt>struct TheType_t</tt> to <tt>TheType</tt> with its given definition. The <tt>TheType_t</tt> is the tag-name of the struct where <tt>TheType</tt> is the really type name. The writing-style with <tt>_t</tt>-suffix is recommended and usual but not a fix rule.

The forward declaration of a pointer-type straightens a complex dependencies of header files. In Java there is not a adequate possibility. A Java-interface is the way of straighten still.

==Criterion for Components==
* Able to define and describe as entity.
* Able to test as entity.
* Dependencies of parts to other components: If any new part creates a new dependency to a foreign component, it should be realized as critical. Either the new dependency is desired, or the part should not be a part of this component.
* Conglomerate of several functionality: It is okay, if the modules doesn't need other components (see ''dependencies''). A component can contain a functionality, which is not need in the typical use-cases, but it is offered for special usages.
* Frequently changes in conglomerate parts: Any change in the sources of the component builds a new release of the whole component, which should be checked for relevance for all usages. Parts, which are frequently changed, but they are not a core functionality of the component, should be dissolved from the component therefore.
* Self-reliance: The same functionality should not scattered to several components. Only one component should be responsible to that functionality.

Component

Admin — Mon, 21 Mar 2011 09:02:36 GMT

Admin: Protected "Component" ([edit=autoconfirmed] (indefinite) [move=autoconfirmed] (indefinite))

==Navigation==
* up: [[Main_Page]]
* down: [[Components_of_vishia-Java]] [[Components_of_CRuntimeJavalike]]

==Components and modules, re-using==

A software should consist of more as one component. Each component should be able to describe, program and test independent of the application which uses it. A component may be able to use in several applications. Then it is reuseable.

Modules are the finer granularity inside components or inside the core of the application. Each module should be able to describe, program and test independently too. Modules may be one C/h-file or a package in Java or some related files.

A class in ObjectOrientation is the more finer granularity inside modules. A class in the C-programming is a logical coherence between one data structure and related subroutines. One class may be presented exactly with one source-file.

==Dependencies between components, modules, classes==

If another class is used inside a class, it depends on it. Formally it depends on the signature of the methods of the class. Really the functionality depends on the functionality of the called methods.

For a independent test of a class, module or component it may be necessary to abstract the functionality of the depending stuff. The behavior of the depending stuff should be replaced by a simulation or emulation.

===Dependencies defines components===

If a component need the presence of another component while compiling or linking, then the component depends on the other component formally. Components should be tailored to specified other components. If any other component is need only for a special function, which isn't the main stream functionality of the component, it is disagreeable. The user of the component should attend to the other component, which isn't need really. It is additional work to do without benefit.

Components can be depended on any common functions of a platform, which are present anytime. For example all base class of a Java Virtual Machine and its <tt>rt.jar</tt> library can be used in the Java-sources. Then the component may be designated as '''independent of any others'''.

If a component depends on another specified component, it builds a system of components. Such a component-system should not be complex. '''Dependency-breaker''' are need. The dependency breakers allow a formally translation (compilation) without the presence of other complex components. For running (linking), any incarnation of the ''components behind the dependency-breaker'' should be present. But that components may be replacements for simulation etc. if necessary.

===Dependencies in a application===

There are '''horizontal''' and '''vertical dependencies''': If a class/module/component can be created, described and tested independent on another class/module/component, it is deeper in vertical or parallel in horizontal layer. If a class/module/component needs another one, it is above that in vertical layer. ''It needs'' means, in the real application it is associated to it and calls some methods from there. For the independently test all needed classes/modules/components may be able to replace.

===Interfaces as dependency-breaker===

There is a problem: Module_A needs some methods from Module_B and on the other hand Module_B needs some things from Module_A. Both modules are parallel in layer, but there are not able to develop and test independently.

Either the both modules are not two separated modules, the functionality should be combined in one module. - Or it should be separated using interfaces.

The ''interface'' is a language-element of Java. It defines methods with its signature, but without implementation. The description, "''what should the method do, which argument values are expectable, meaning of the return value''" belongs to the method anyway. In C++ interfaces are able to create in a similar kind as Java. It is a class with only virtual abstract methods and without any implementation:

class InterfaceExample { //C++-interface
virtual int aMethod(int arg) = 0;
};

====Classic C - Headerfiles as interface====

The classic C programming knows headerfiles, which ones play the role of interfaces: Function prototypes has the same appearance as a method definition in a Java-interface or a virtual abstract methods:

extern int aFunction(int arg);

The difference to Java and C++-virtual-methods is: It is static linked. There can be only one implementation in a executable, whereby in Java and C++ the interface can be implement by several classes which are instantiated independently. It is a ''dynamic link''.

But the principle of dependency-break is the same.

====Classic C- struct forward declaration as dependency break====

In C and C++ there is a nice possibility to prevent to many include-necessities:

struct TheType_t;

typedef struct Example_t{
struct TheType_t* pointer;
} Example;

Inside the Example-struct a pointer of TheType is need. But <tt>TheType</tt> itself may left unknown. It isn't necessary to know the type while compiling this struct. It is not necessary to include the typedef of <tt>TheType</tt>

If the pointer is used in the implementation (the C-file), then the type should be known. The implementation-File includes the definition of:

typedef struct TheType_t{
int someStuff;
}Thetype;

Now the compiler checks the matching of <tt>struct TheType_t</tt> to <tt>TheType</tt> with its given definition. The <tt>TheType_t</tt> is the tag-name of the struct where <tt>TheType</tt> is the really type name. The writing-style with <tt>_t</tt>-suffix is recommended and usual but not a fix rule.

The forward declaration of a pointer-type straightens a complex dependencies of header files. In Java there is not a adequate possibility. A Java-interface is the way of straighten still.

==Criterion for Components==
* Able to define and describe as entity.
* Able to test as entity.
* Dependencies of parts to other components: If any new part creates a new dependency to a foreign component, it should be realized as critical. Either the new dependency is desired, or the part should not be a part of this component.
* Conglomerate of several functionality: It is okay, if the modules doesn't need other components (see ''dependencies''). A component can contain a functionality, which is not need in the typical use-cases, but it is offered for special usages.
* Frequently changes in conglomerate parts: Any change in the sources of the component builds a new release of the whole component, which should be checked for relevance for all usages. Parts, which are frequently changed, but they are not a core functionality of the component, should be dissolved from the component therefore.
* Self-reliance: The same functionality should not scattered to several components. Only one component should be responsible to that functionality.

Components of CRuntimeJavalike

Admin — Sun, 13 Mar 2011 11:07:55 GMT

Admin: links to header

==Navigation==
* up: [[Main_Page]] / [[Component]]
* down: see chapters

==Overview==
CRuntimeJavalike is a tree of C-files with makefiles to build libraries. All files are written by Hartmut Schorrig, www.vishia.org. They are used in some applications in profession too (with second license model). It is a conglomeration of different things, of course.

The CRuntimeJavalike can be used in any application. It contains a OSAL-layer, which is provided for Windows and Linux. The OSAL-layer have to be adapted for other operation systems. Some adaption exists and are tested and used in profession. With adapting the OSAL-layer the sources can be used and the examples can run on any platform.

==Distribution and sources in internet==

* distribution: [[http://sf.net/projects/java2c sf.net/projects/java2c]] The CRuntimeJavalike is distributed as part of the Java2C-Translator. But it can be used without this translator too. Download the distribution and use only the CRuntimeJavalike. [[http://sf.net/projects/zbnf sf.net/projects/zbnf]]
* bazaar-archive on [[https://launchpad.net/jc/trunk launchpad.net/jc]]
* description, home-site on [[http://www.vishia.org/Jc www.vishia.org/Jc]]

==OSAL==
See [[OSAL]]. The OSAL-component contains
* C-files, which are special written for the appropriate operation system.
* One Headerfile, which contains some depending definitions which should be adapted to the platform, os and compiler. It is the [[os_types_def]].h.
* Headerfiles, which are independent of the operation system. It describes the OSAL-interface.
* Headerfiles, which contains simple C-definitions and declarations. It are independent of compiler, platform and os.
** [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_Exception.h.html include/Fwc/fw_Exception.h]]: Exception handling for C and C++ inclusive Stacktrace-Mechanism. In C a longjmp is used to throw. (longjmp.h is defined in the old Standards of C and in C99 too).
** [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_Formatter.h.html include/Fwc/fw_Formatter.h]]: Declaration of methods for formatting Strings. It include time-formattings. It is similar to sprintf.
** [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_MemC.h.html include/Fwc/fw_MemC.h]]: Definition of a struct MemC with pointer and its size. Some macros to handle with pointer. Some function prototypes for MemC-handling.
** [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_Readline.h.html include/Fwc/fw_Readline.h]]: Support of reading lines from a file. A line can be terminated with 0d, 0a or any combination (Windows, Unix, Mac-conventions all in one). The os_file.h is used as interface to read a file.
** [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_SimpleC.h.html include/Fwc/fw_SimpleC.h]]: Some basicly simple macros and function declarations.
** [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_String.h.html include/Fwc/fw_String.h]]: Basic functions for String storing in a struct StringJc. It is the alternative to zero-terminated C-Strings. The pointer and the length is stored. The basic functions are a bridge between 0-terminated C-strings and StringJc-referenced strings.
** [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_ThreadContext.h.html include/Fwc/fw_ThreadContext.h]]: The ThreadContext is managed in the OSAL, but its struct is defined here.
** [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_timeconversions.h.html include/Fwc/fw_timeconversions.h]]: struct and funtion declarations for time conversions: A timestamp should be stored internally in form of currently seconds and microseconds after a start time. The conversion to a human readable time should be done only for presentation. The routines support the conversion.
** [[http://www.vishia.org/Jc/html/sources/include/Fwc/fw_Va_list.h.html include/Fwc/fw_Va_list.h]]: An appreciation to the < stdarg.h> concept. The value as new: Any argument-type of a variable argument list is described with one char in a char*-string with one char. With the knowledge of the correct type any users function can be use the variable argument more correctly. Usual any other information should be necessary, for example the format-String of sprintf. This header and functions are used in fw_formatter.h

* C-files, which contains common sources for OSAL
* C-files, which contains common sources for simple C-functions. It can be used in the OSAL-Adaption.

With this Sources a application can be written os-indenpendent. All this sources are independent of the Java2C-thinking. This sources are not complex. There are not any assumption to Java.

Components of CRuntimeJavalike

Admin — Sun, 13 Mar 2011 10:17:37 GMT

Admin:

==Navigation==
* up: [[Main_Page]] / [[Component]]
* down: see chapters

==Overview==
CRuntimeJavalike is a tree of C-files with makefiles to build libraries. All files are written by Hartmut Schorrig, www.vishia.org. They are used in some applications in profession too (with second license model). It is a conglomeration of different things, of course.

The CRuntimeJavalike can be used in any application. It contains a OSAL-layer, which is provided for Windows and Linux. The OSAL-layer have to be adapted for other operation systems. Some adaption exists and are tested and used in profession. With adapting the OSAL-layer the sources can be used and the examples can run on any platform.

==Distribution and sources in internet==

* distribution: [[http://sf.net/projects/java2c sf.net/projects/java2c]] The CRuntimeJavalike is distributed as part of the Java2C-Translator. But it can be used without this translator too. Download the distribution and use only the CRuntimeJavalike. [[http://sf.net/projects/zbnf sf.net/projects/zbnf]]
* bazaar-archive on [[https://launchpad.net/jc/trunk launchpad.net/jc]]
* description, home-site on [[http://www.vishia.org/Jc www.vishia.org/Jc]]

==OSAL==
See [[OSAL]]. The OSAL-component contains
* C-files, which are special written for the appropriate operation system.
* One Headerfile, which contains some depending definitions which should be adapted to the platform, os and compiler. It is the [[os_types_def]].h.
* Headerfiles, which are independent of the operation system. It describes the OSAL-interface.
* Headerfiles, which contains simple C-definitions and declarations. It are independent of compiler, platform and os.
** include\Fwc\fw_Exception.h: Exception handling for C and C++ inclusive Stacktrace-Mechanism. In C a longjmp is used to throw. (longjmp.h is defined in the old Standards of C and in C99 too).
** include\Fwc\fw_Formatter.h: Declaration of methods for formatting Strings. It include time-formattings. It is similar to sprintf.
** include\Fwc\fw_MemC.h: Definition of a struct MemC with pointer and its size. Some macros to handle with pointer. Some function prototypes for MemC-handling.
** include\Fwc\fw_Readline.h: Support of reading lines from a file. A line can be terminated with 0d, 0a or any combination (Windows, Unix, Mac-conventions all in one). The os_file.h is used as interface to read a file.
** include\Fwc\fw_SimpleC.h: Some basicly simple macros and function declarations.
** include\Fwc\fw_String.h: Basic functions for String storing in a struct StringJc. It is the alternative to zero-terminated C-Strings. The pointer and the length is stored. The basic functions are a bridge between 0-terminated C-strings and StringJc-referenced strings.
** include\Fwc\fw_ThreadContext.h: The ThreadContext is managed in the OSAL, but its struct is defined here.
** include\Fwc\fw_timeconversions.h: struct and funtion declarations for time conversions: A timestamp should be stored internally in form of currently seconds and microseconds after a start time. The conversion to a human readable time should be done only for presentation. The routines support the conversion.
** include\Fwc\fw_Va_list.h: An appreciation to the < stdarg.h> concept. The value as new: Any argument-type of a variable argument list is described with one char in a char*-string with one char. With the knowledge of the correct type any users function can be use the variable argument more correctly. Usual any other information should be necessary, for example the format-String of sprintf. This header and functions are used in fw_formatter.h

* C-files, which contains common sources for OSAL
* C-files, which contains common sources for simple C-functions. It can be used in the OSAL-Adaption.

With this Sources a application can be written os-indenpendent. All this sources are independent of the Java2C-thinking. This sources are not complex. There are not any assumption to Java.

Components of CRuntimeJavalike

Admin — Sun, 13 Mar 2011 09:58:43 GMT

Admin: Protected "Components of CRuntimeJavalike" ([edit=autoconfirmed] (indefinite) [move=autoconfirmed] (indefinite))

Components of CRuntimeJavalike

Admin — Sun, 13 Mar 2011 09:40:38 GMT

Admin: Created page with '==Navigation== * up: Main_Page / Component * down: see chapters ==Overview== CRuntimeJavalike is a tree of C-files with makefiles to build libraries. All files are writt…'

Os file

Admin — Sun, 06 Mar 2011 11:00:31 GMT

Admin:

==Contains==
* Handling with opened streams, adequate fopen, fread, fwrite, flock, ftell, fskip
* Handling with file entries in a directory: exists, write-ability, date last modified, length, absolute path
* supports pipes of command in/output: stdin, stdout, stderr

==Situation for embedded platforms==
A file system how it is known from the PC-based software in C is not present in some embedded devices.

But a handling of special files may be possible. There may be present only a few files with given names, or some files in only one directory level which are stored in the RAM, a flash file system, a remote file system etc.

User software should handle with files, independently how it is deployed in the given hardware platform. If there are only special files, the user software should regard this situation using the given special file-paths while open it. But the user software should not depend on the hardware implementation of the file system. All algorithm should be able to test on PC-platform.

==Situation of standardizing in C==

The old C knows two standard to access files:

* Lo-level file-io using open, read, write with a int handle. This was the originally intension in C. This concept founds the stream-handling of UNIX using pipes, standard- and error.output on console etc.

* Buffered file-io using fopen, fread, fwrite, fflush with a structured file handle named <tt>FILE*</tt> defined in < stdio.h>. This was a second stage of file handling in C.

The interface between the linux-core and the library-layer is adequate to the lo-level-file-system.

But in C-programming only the buffered file-io is usual now. The C99-standard doesn't know the routines of the lo-level-file-io. The buffered file-io regards the <tt>stdout</tt>, <tt>stdin</tt> and <tt>stderr</tt> for piping command line applications too. But they are not the int-values 0..2. Rather than they are special FILE-objects supported by the std-library.

Any C-compiler at any embedded system may offer this file-io-standard-routines and data, but sometimes not in that way how the hardware implements it really. To access the file system which is supported by special packages the routines of the special package should be used instead. The methods are provided in adequate interfaces with adequate names of the routines, but not identical. Often the file-system-component is not integrated in the standard library of the compiler.

The query of a last-modified timestamp etc. is defined in C in the POSIX-standard with the method <tt>fstat()</tt> defined in the <tt><sys/stat.h></tt>-header. This standard is regarded in some C- and C++ compiler-libraries but it isn't standardized in the C99-standard and it isn't present in a standardized form for any platform. Therefore the POSIX-standard for that isn't able to use outside of UNIX/Linux/PC programming. There is not a really standard.

Therefore the os_file OSAL provides a able-to-use interface. The implementation can use the POSIX-standard if exists or adequate mechanism, which exists in most of file-system-components.

==Comparison with Java-file-handling==

Java knows the <tt>java.io.InputStream</tt> and <tt>java.io.OutputStream</tt>. This both abstract classes are the basics for stream in/out, which are comparable with the lo-level file-io of C respectively the standard file-io using the <tt>FILE*</tt> descriptor, but without <tt>fprintf</tt>-capability. The last one is provided with the <tt>java.io.PrintStream</tt>, derived from java.io.OutputStream. The class java.lang.System contains three references named <tt>out</tt>, <tt>err</tt> and <tt>in</tt> of type of PrintStream respectively InputStream which represents the pipe-concept of command line invocations in the adequate way as C's <tt> stdin</tt>, <tt>stdout</tt> and <tt>stderr</tt>.

The handling with file entries in a directory is supported with the class <tt>java.io.File</tt> with its methods <tt>exists()</tt>, <tt>lastModified()</tt> etc. This class is comparable with the <tt>struct OS_FileDescription</tt> and its associated routines defined in the <tt>os_file.h</tt>.

==Using os_file.h instead file handling with stdio.h==

How it is described in the chapter above, the standard-file-handling doesn't resolve the real expected functionality. Thats why the user programming should not use the standard-file-handling but the os_file-handling. The OSAL-layer adapts the real file handling of the given environment. It can do it because it is a module associated to the users system component, not only associated to the compiler provider.

Sometimes the handling of files is wrapped with functionality of a higher level than the C-standard-file-io. The user uses this wrapper instead the more lo-level C-functions. Inside the wrapper the os_file-routines are called. In that kind the user hasn't any cohesion to the os_file or standard-file handling immediately. The usage of wrappers provides a higher-level interface for the user programming.

==Description of os_file - Interface==

===Query of properties of files===

The struct <tt>OS_FileDescription</tt> contains the properties for

* fileLength
* flags for query
** exists
** canRead
** canWrite
** hidden
** directory entry or file
* timestamp last modified
* absolute (internal) path of the file
* position of name and relativ path in file to support query it.

The method <tt>os_initFileDescription(this, filepath)</tt> intializes the struct without calling the operation system. The method <tt>os_getFileDescription(this)</tt> accesses the operation system and reads the data from directory entries. The implementation uses <tt>fstat(...)</tt> if a POSIX-compatible access is available.

===stream in/out===
TODO
===file locking===
TODO

Os file

Admin — Sun, 06 Mar 2011 10:14:29 GMT

Admin: Protected "Os file" ([edit=autoconfirmed] (indefinite) [move=autoconfirmed] (indefinite))

==Situation in embedded software==
A file system how it is known from the PC-based software in C is not present in some embedded devices.

But a handling of special files may be possible. There may be present only a few files with given names, or some files in only one directory level which are stored in the RAM, a flash file system, a remote file system etc.

User software should handle with files, independently how it is deployed in the given hardware platform. If there are only special files, the user software should regard this situation using the given special file-paths while open it. But the user software should not depend on the hardware implementation of the file system. All algorithm should be able to test on PC-platform.

==Situation of standardizing in C==

The old C knows two standard to access files:

* Lo-level file-io using open, read, write with a int handle. This was the originally intension in C. This concept founds the stream-handling of UNIX using pipes, standard- and error.output on console etc.

* Buffered file-io using fopen, fread, fwrite, fflush with a structured file handle named <tt>FILE*</tt> defined in < stdio.h>. This was a second stage of file handling in C.

The interface between the linux-core and the library-layer is adequate to the lo-level-file-system.

But in C-programming only the buffered file-io is usual now. The C99-standard doesn't know the routines of the lo-level-file-io. The buffered file-io regards the <tt>stdout</tt>, <tt>stdin</tt> and <tt>stderr</tt> for piping command line applications too. But they are not the int-values 0..2. Rather than they are special FILE-objects supported by the std-library.

Any C-compiler at any embedded system may offer this file-io-standard-routines and data, but sometimes not in that way how the hardware implements it really. To access the file system which is supported by special packages the routines of the special package should be used instead. The methods are provided in adequate interfaces with adequate names of the routines, but not identical. Often the file-system-component is not integrated in the standard library of the compiler.

==Using os_file.h instead file handling with stdio.h==

How it is described in the chapter above, the standard-file-handling doesn't resolve the real expected functionality. Thats why the user programming should not use the standard-file-handling but the os_file-handling. The OSAL-layer adapts the real file handling of the given environment. It can do it because it is a module associated to the users system component, not only associated to the compiler provider.

Sometimes the handling of files is wrapped with functionality of a higher level than the C-standard-file-io. The user uses this wrapper instead the more lo-level C-functions. Inside the wrapper the os_file-routines are called. In that kind the user hasn't any cohesion to the os_file or standard-file handling immediately. The usage of wrappers provides a higher-level interface for the user programming.

Inspector datagram

Admin — Sun, 06 Mar 2011 08:38:12 GMT

Admin: first

== Telegram-structure ==

If Ethernet is present, UDP-telegrams are used. The same informations as ''datagram'' can be transfered inside a hardware with dual-port-RAM-access, or in older or cheeper systems with serial link (RS232), or adequate.

Any datagram consist of a unified header of 16 Byte. After them so named //information units// are disposed. Any information unit consists of a header of 8 byte, following by different data. The header contains the length of the information unit.

The components of the datagram are defined for C/C++-usage in the headerfile //DataExchange_Inspc.h//.

===Syntax for datagrams===

The datagrams are not simple data structs, but compositions of data. Therefore the usage of C-struct-definitions needs to many verbal explanations. A strong syntactical definition is more exactly. For the syntax description the ZBNF is used. ZBNF is similar to the well known BNF or EBNF, but it defines the semantic aspect in the syntax description too. The ZBNF is described in [[http://www.vishia.org/ZBNF]]. The enhancement of ZBNF for binary data, like used here, is described in [[http://www.vishia.org/ZBNF/sf/ZBNF/docu/ZbnfBinary_en.html]].

===Basic elements used in the datagram for inspector-data-communication===

//**InspcDatagram::=<@HEADSIZE=16> <@0+2:SIZE?nrofBytes> <@2+2?entrant="> <@4+4?encryption> <@8+4?seqnr> <@12+1?" answerNr=" <@13+3?reserve>.**//

It is the head of any datagram.
* entrant: is an identifier of the instance inside a target which should be addressed. TODO: Note: It is a negative number yet, to distinguish to the headless telegrams.
* encryption: is an information for encryption of the content after this head. Note: The encryption is planned but not designed yet.
* seqnr: identifies a telegram and its associated answer telegram. In generally, a command-datagram should use any number which is unique for a longer time. The answer should mirror this same number. This is the only contract. In addition, the number can be built with the current timestamp. The bits 31..4 contains the current milliseconds after 1970 (fractional part) and the bits 3..0 may be count more as one telegram in the same millisecond. The same sequence number can be occured after 4 days, this is a long enough distance of time. The time information can be used for debugging.
* answerNr: A answer telegram may be consist of more as one UDP-Telegram. The first telegram in numbered by 1. The next telegram is countered here. The last telegramm is dedicated by set bit 7. It means, if the answer consists of one telegram, it has the value 0x81 here. If the answer consists of 2 telegrams, there are numbered here with 0x01, 0x82. If the receiver doesn't get all telegrams (lost telegrams), than the command should be repeated.

//**Item::=<@HEADSIZE=8> <@0+2:SIZE?nrofBytes> <@2+2?cmd> <@4+4?order>.**//

It is the head for any information unit inside a <InspDatagram>...</InspDatagram>. An <Item> can have children. So the general form of a datagram may be written as

//**<InspDatagram><Item:>...<:Item><Item:>...<:Item></Datagram>.**//

The superior componentes with <Item> as head are subtly differentiated and named with an own syntactical name. See for example <cmdValueByPath>.

//**ItemAckn::=<Item cmd=1 />.**//

//**ItemNackn::=<Item cmd=1 />.**//

Acknowledge or non-acknowledge answer to a request. If the answer should have data, the data are returned, or the <ItemNackn> is returned if the cmd isn't able to proceed. The <ItemNack> contains the order-number to assign the request. Especially if a path is false, a <ItemNackn> is returned.

//**Value8byte::=<@SIZE=8> [ <@0+4:float?float> | <@0+8:double?double> | <@0+8?long> | <@4+4?int> | <@6+2?short> | <@7+1?byte>].**//

A <Value8byte>-value is a pure value in 8 bytes. In case of float, 4 bytes are unused. In case of integer with less bytes as 8, it is the same as long in big-endian-presentation. TODO setting of char16? The type of data isn't described in this element. Normally the operator (GUI) knows the type of the element inside the target and prepares the proper type for the target.

//**TypeId::=<@SIZE=1?> <@0+0?id>**//

It is one byte which contains the identification for a type.

//**int64Value ::=<@SIZE=9?> <TypeId id=0xe2> <@1+8?value>.**//

//**uint64Value::=<@SIZE=9?> <TypeId id=0xe3> <@1+8?value>.**//

//**int32Value ::=<@SIZE=5?> <TypeId id=0xe4> <@1+4?value>.**//

//**uint32Value::=<@SIZE=5?> <TypeId id=0xe5> <@1+4?value>.**//

//**int16Value ::=<@SIZE=3?> <TypeId id=0xe6> <@1+2?value>.**//

//**uint32Value::=<@SIZE=3?> <TypeId id=0xe7> <@1+2?value>.**//

//**int8Value ::=<@SIZE=2?> <TypeId id=0xe8> <@1+1?value>.**//

//**uint8Value ::=<@SIZE=2?> <TypeId id=0xe9> <@1+1?value>.**//

//**floatValue ::=<@SIZE=5?> <TypeId id=0xec> <@1+4:float?value>.**//

//**doubleValue::=<@SIZE=9?> <TypeId id=0xed> <@1+8:double?value>.**//

//**char8Value ::=<@SIZE=2?> <TypeId id=0xee> <@1+1?value>.**//

//**char16Value ::=<@SIZE=3?> <TypeId id=0xef> <@1+2?value>.**//

//**boolValue ::=<@SIZE=2?> <TypeId id=0xf6> <@1+1?value>.**//

They are representations of the primitive values. The values are the image of the bit representation of the type in the hardware. It is written in big-endian always! The first byte is the type-identifier-byte.

//**StringValue::= <TypeId id:SIZE=1..0xbf> { <@*?char> }</TypeId>.**//

The length of the StringValue is the number of chars +1, because the length-information counts the length-byte too.

===Presentation of string-given pathes===

//**PathValue::=[{ <$?fieldIdent> [**// {{{[}}}//**<#?index>**//{{{]}}}//** | [<?questCollectionSize> **//{{{[?]}}}//** | **//{{{<?>}}}//** ] |]**// {{{.}}}//** }| **//{{{.}}}//** ].**//

The <PathValue> describes the access to any element inside the structure of data. It is given as string of chars.
Examples for valid paths are:
* ".": The first node
* "myAppl.data.": deeper node.
* "myAppl.x[10]." : an element of an array
* "myAppl.x[10].a." : an element inside an array-element
* "myAppl.x[?]." : The container x is asked to his collection size.
* "myAppl.x<?>." : The same above, the <> should associate a non-array-container, a List or Map

ZBNF-syntax-notification:
* The <$?fieldIdent> denotes an //identifier// with the meaning //fieldIdent//.
* An index is optional for any <$fieldIdent>. The notification in [...] means an option, like usual in BNF.
* The notification of \[ and \] means the brackets as characters in the text. <#?index> denotes a number with meaning //index//.
* {...} is a repetition, passing at least one time. [...|...] is the choiceable-option.

===Items in datagrams, commands and its answer===

===Request the structure of data===

//**cmdGetFields::=<Item cmd=0x10:><PathValue><:Item>.**//

/**anwerFields::={ <Item cmd=0x14:><$?Fieldident>[ \[ <#?fixArraySize> | ? <?dynamicArray> \] | \<?\> <?container> |]<:Item> }.**//

The command supplies a path. The answer consists of more as one Item, all with the same order-id, one item describes one field of the requested data structure. TODO the real-type is not answered. it is only able to guess from the elements and from the type of the reference. If the reference is the same, it may be ok. But for derived classes the type should be returned too.

===Request a value===

//**cmdValueByPath::=<Item cmd=0x30:><PathValue><:Item>**//

//**answerValue::=<Item cmd=0x26:> [ <int64Value> | <uint64Value> | <int32Value> | <uint32Value> | <int16Value>| <uint16Value> | <int8Value> | <uint8Value> | <floatValue> | <doubleValue> | <char8Value> | <boolValue> | <StringValue> ] <:Item>.**//

<cmdValueByPath> is a part inside <InspDatagram>...<cmdValueByPath />...</InspDatagram>, which is send from the operator to the target. The targets sends an answer telegram which contains <InspDatagram>...<answerValue />...</InspDatagram>. The Item.order is reflected from the cmd to the answer. The InspDatagram.seqnr is reflected from the cmd telegram to the answer telegram. There can be more as one command in one Datagram from operator to target, which is anwered in one datagram with all answers.

<cmdValueByPath> requests the value of the given path. The answer is given in the form <answerValue>. If the last element of the path is a primitive numeric value, then its value is answered in the binary representation. If the element is a character string, the contained String is returned, but maximal the first 191 characters. If the element is a complex one and it based on Object, the toString()-method is invoked which returns a string. In the other case the address of the element is returned as String in form "@address".

===Set a value===

//**SetValueByPath::=<Item cmd=0x35:> <Value8byte /> <PathValue /> <:Item>**//

//**<answerValue>**//

The answer is <answervalue> where the re-read value is returned. The type of value should be correct given. The value is set in the target with the given bytes in <Value8byte> without conversion.

===Store sets of pathes in a target or reflection unit (agents)===

A target may store some pathes, which is a agent at the GUI. It is possible that this are set-values (path + value), which are executed in the target device on startup automatically to set initial values or parameter.

====Create a file for agent items====

//**cmdCreateAgentFile::=<Item: cmd=0x50 > <$/\.?filepath> <:Item>. **//

//**answerCreateAgentFile: <Item cmd=0x51 :> <@8+2?nrFile> <:Item>.**//

It opens respectively creates a file to store persistent values. An existing file will be deleted. It means the stored persistent pathes with their values are removed from the target. The intension is, send newly. The filepath may consist of / as separator of directories and dots for extension. The possibilities of filepath-notifications depends on the ability of the target system. There may be a simple file system which accepts only deterministic names.

The answer returnes a number in positive range as handle, which have to be used for the items of the agent.

If the command is repeated by the same source, it is repeately executed. If the command is sent from another source, while the same file is opened, a negativ acknowledge is returned.

If a negativ acknowlege is returned, the same answer but with nrFile = -1 is sent.

====Get a value and save ====

//**cmdGetAgentValueByPath::=<Item cmd=0x56:> <@8+2?nrFile> <Value8byte /> <PathValue /> <:Item>**//

//**<answerValue>**//

The answer is <answerValue> with the actual content. Additinally the Item is stored in the file of agent.

====Set a value and save (persistent)====

//**cmdSetPersistValueByPath::=<Item cmd=0x54:> <@8+2?nrFile> <Value8byte /> <PathValue /> <:Item>**//

//**<answerValue>**//

The answer is <answervalue> where the re-read value is returned. The type of value should be correct given. The value is set in the target with the given bytes in <Value8byte> without conversion. This Item is registered in a persistent-agent-file inside the target device. Its number is given in nrFile in the datagram. The file should be opened and closed with extra items in another datagrams.

====Request the content of a agent====

//**cmdRequestAgent::=<Item cmd=0x58:><$/\.?filepath> <:Item>. **//

The answer consists of

//**answerRequestAgent::={<InspcDatagram:>{<answerAgentSetItem>|<answerAgentGetItem>}<:InspcDatagram>}**/

It means, all stored <answerAgentItem> in the requested file are returned in one or more Datagrams.

//**answerAgentSetItem::=<Item cmd=0x59:> <@8+2?nrFile> <Value8byte /> <PathValue /> <:Item>**//

The value is the value which is stored. The answer doesn't access to data.

//**answerAgentGetItem::=<Item cmd=0x5b:> <@8+2?nrFile> <PathValue /> <:Item>**//

The item contains only the path. The answer doesn't access to data.

====Closes a file for persist values====

//**cmdCloseAgentFile::=<Item cmd=0x52:> <@8+2?nrFile> <:Item>. **//

//**answerCloseAgentFile::= <Item cmd=0x53>. **//

The file is closed now. Following requests <SetPersistValueByPath> are answered with <ItenNackn> and they are not executed. TODO should they set non-persistent?

The file will be closed automatically if no close command is received in a timeout time, which depends on the target. It is about a few seconds. It means, if the communication is aborted, no problem occurs. The behaviour of the target is **stateless**, after the timeout. But the agent file may be confuse then because not all items are stored.

===General Syntax of a whole telegram===

WholeInspDatagramToTarget::=<InspDatagram> { <cmdValueByPath> | <cmdGetFields> | <TODO> } </InspDatagram>.

WholeInspDatagramFromTarget::=<InspDatagram> { <answerValue> | <TODO> } </InspDatagram>.

Main Page

Admin — Sun, 06 Mar 2011 08:35:06 GMT

Admin:

This site holds information about programming for embedded software in an ObjectOriented style. Ideas and concepts of the Java programming language are integrated in this thinks. Some articles describe software-engineering-topics.

==Base links==
* [[Java4C]] - why Java-thinking and Java-using for the C-programming
* [[CRuntimeJavalike]] - A base library for embedded C-software
* [[Java2C]] - A translator from Java-sources to C-sources
* [[Component]] - Building the application with components and moduls
* [[Bazaar]] - A Source Version System

==Java4C==
* [[Java4C]] - why Java-thinking and Java-using for the C-programming

==CRuntimeJavalike==
* [[CRuntimeJavalike]] - A base library for embedded C-software
===OSAL===
* [[OSAL]] - The interface to the operation system with its application layer
* basics: [[os_types_def]] // [[os_AtomicAccess]] // [[os_error]]
* somethings: [[os_mem]] // [[os_time]] // [[os_file]] // [[os_endian]]
* MultiThreading: [[os_thread]] -- [[os_waitnotify]] -- [[os_sync]] -- [[os_socket]]
* [[os_Shared_Memory]] -- [[Dual port RAM]] -- [[InterProcessCommunication]]
* [[os_driver]] operation access at driver level

==Java2C==
* [[http://www.vishia.org/Java2C www.vishia.org/Java2C]]
* [[http://sourceforge.net/projects/java2c Java2C on sourceforge]]

==Components, Dependencies==
* [[Component]] - Building the application with components and modules - common description

===Components of vishia-Software===
* [[Components of vishia-Java]] - presentation of components from all Java - sources of org/vishia
* [[Components of CRuntimeJavalike]] - presentation of components from C-sources

===Dependencies===
* [[Dependency]]

====Dependency-Topics of C====
* [[forward declaration of struct]]
* [[forward declaration of functions in header]]

====Dependency-Topics of ObjectOrientation (Java, C)====

* TODO

==Bazaar==
* [[Bazaar]] - A Source Version System
* [[Bazaar-Notes]]: discussion (german) about Source-Management and directory structures

==The key author of this site==

has experience in embedded programming since 1977, beginning with Assembler programming with the Z80-processor. I'm working for a company in germany in themes of embedded control. This site presents experiences independently of concretely job definitions. Hartmut Schorrig, [[http://www.vishia.org www.vishia.org]]

==The mission of this site - Your contribution==

Exchange of experiences. You can take place on discussion. You can complement the text of the pages with your experience and knowledge. You can improve the appearance of the text.

It is necessary to register with a user name to this site.

Future: [[Inspector datagram]]

Os file

Admin — Sun, 06 Mar 2011 08:02:08 GMT

Admin: first

Main Page

Admin — Sun, 06 Mar 2011 07:32:42 GMT

Admin: /* OSAL */

This site holds information about programming for embedded software in an ObjectOriented style. Ideas and concepts of the Java programming language are integrated in this thinks. Some articles describe software-engineering-topics.

==Base links==
* [[Java4C]] - why Java-thinking and Java-using for the C-programming
* [[CRuntimeJavalike]] - A base library for embedded C-software
* [[Java2C]] - A translator from Java-sources to C-sources
* [[Component]] - Building the application with components and moduls
* [[Bazaar]] - A Source Version System

==Java4C==
* [[Java4C]] - why Java-thinking and Java-using for the C-programming

==CRuntimeJavalike==
* [[CRuntimeJavalike]] - A base library for embedded C-software
===OSAL===
* [[OSAL]] - The interface to the operation system with its application layer
* basics: [[os_types_def]] // [[os_AtomicAccess]] // [[os_error]]
* somethings: [[os_mem]] // [[os_time]] // [[os_file]] // [[os_endian]]
* MultiThreading: [[os_thread]] -- [[os_waitnotify]] -- [[os_sync]] -- [[os_socket]]
* [[os_Shared_Memory]] -- [[Dual port RAM]] -- [[InterProcessCommunication]]
* [[os_driver]] operation access at driver level

==Java2C==
* [[http://www.vishia.org/Java2C www.vishia.org/Java2C]]
* [[http://sourceforge.net/projects/java2c Java2C on sourceforge]]

==Components, Dependencies==
* [[Component]] - Building the application with components and modules - common description

===Components of vishia-Software===
* [[Components of vishia-Java]] - presentation of components from all Java - sources of org/vishia
* [[Components of CRuntimeJavalike]] - presentation of components from C-sources

===Dependencies===
* [[Dependency]]

====Dependency-Topics of C====
* [[forward declaration of struct]]
* [[forward declaration of functions in header]]

====Dependency-Topics of ObjectOrientation (Java, C)====

* TODO

==Bazaar==
* [[Bazaar]] - A Source Version System
* [[Bazaar-Notes]]: discussion (german) about Source-Management and directory structures

==The key author of this site==

has experience in embedded programming since 1977, beginning with Assembler programming with the Z80-processor. I'm working for a company in germany in themes of embedded control. This site presents experiences independently of concretely job definitions. Hartmut Schorrig, [[http://www.vishia.org www.vishia.org]]

==The mission of this site - Your contribution==

Exchange of experiences. You can take place on discussion. You can complement the text of the pages with your experience and knowledge. You can improve the appearance of the text.

It is necessary to register with a user name to this site.

Os Shared Memory

Admin — Sun, 06 Mar 2011 05:47:03 GMT

Admin: cont

Shared memory is a memory-area, which is able to access from more as one process. It is a possibility given in some platforms. A process in this meaning is a portion of software maybe with more as one thread, which is running on the same platform simultaneously with other processes. But the processes are separated in the usage of the resources. Especially they haven't a common memory. It is to protect the processes against failures in the software.

'''The shared memory is not a mechanism, which is able to use on any platform'''. Therefore it is not a part of the common OSAL interface definition.

'''Use InterProcessComm as means of expression instead''':

If shared memory is used, it is a problem of the communication between processes. Therefore the mechanism of [[InterProcessCommunication]] should be used instead:

* <tt>InterProcessComm.open(ChannelSpec);</tt> to open a communication channel. It may create a shared-memory-access-object.
* <tt>InterProcessComm.receive(...);</tt>: Receive any data from another process. It may check the shared memory whether expected information are given. It is not specified which addresses and which information inside the shared memory are checked. The receive operation is a broadcast-receive. To specify a finer granularity in information-receiving, there should be more as one <tt>open(...)</tt>-operations which are associated to parts of information in the shared memory. The <tt>receive(...)</tt>-operation is more ''wait for event''-adequate as ''read memory''. But usual it is it, which are expected in a communication between processes. The user should rather think about ''I will use the shared memory'' but ''I have to get events from another process''. If receive is used for shared memory, the <tt>receive(..., sender)</tt>-method can look to control bits in more as one ranges in shared memory. It can return several data specifying the source of the data in the <tt>sender</tt>.

* <tt>InterProcessComm.send(data, address);</tt>: it sets informations, maybe setting values in the shared memory. The address can be select which range, the data are the byte-data for the range. It is equal to send an information to a specified channel.

* The methods <tt>InterProcessComm.capacityToSendWithoutBlocking(requestedNumber)</tt> and <tt>dataAvailable()</tt> can be used to poll the data situation.

If specific data struct are used inside a shared memory, it should be recognized as a problem of a driver level, not as part of a user program.

Os Shared Memory

Admin — Sun, 06 Mar 2011 05:37:34 GMT

Admin: Protected "Os Shared Memory" ([edit=autoconfirmed] (indefinite) [move=autoconfirmed] (indefinite))

Shared memory is a memory-area, which is able to access from more as one process. It is a possibility given in some platforms. A process in this meaning is a portion of software maybe with more as one thread, which is running on the same platform simultaneously with other processes. But the processes are separated in the usage of the resources. Especially they haven't a common memory. It is to protect the processes against failures in the software.

The shared memory is not a mechanism, which is able to use on any platform. Therefore it is not a part of the common OSAL interface definition.

If shared memory is used, it is a problem of the communication between processes. Therefore the mechanism of [[InterProcessCommunication]] should be used instead:

* <tt>InterProcessComm.open(ChannelSpec);</tt> to open a communication channel. It may create a shared-memory-access-object.
* <tt>InterProcessComm.receive(...);</tt>: Receive any data from another process. It may check the shared memory whether expected information are given. It is not specified which addresses and which information inside the shared memory are checked. The receive operation is a broadcast-receive. To specify a finer granularity in information-receiving, there should be more as one <tt>open(...)</tt>-operations which are associated to parts of information in the shared memory. The <tt>receive(...)</tt>-operation is more ''wait for event''-adequate as ''read memory''. But usual it is it, which are expected in a communication between processes. The user should rather think about ''I will use the shared memory'' but ''I have to get events from another process''.

* <tt>InterProcessComm.send(data, address);</tt>: it sets informations, maybe setting values in the shared memory

Os Shared Memory

Admin — Sat, 05 Mar 2011 21:22:30 GMT

Admin: first

Shared memory is a memory-area, which is able to access from more as one process. It is a possibility given in some platforms. A process in this meaning is a portion of software maybe with more as one thread, which is running on the same platform simultaneously with other processes. But the processes are separated in the usage of the resources. Especially they haven't a common memory. It is to protect the processes against failures in the software.

The shared memory is not a mechanism, which is able to use on any platform. Therefore it is not a part of the common OSAL interface definition.

If shared memory is used, it is a problem of the communication between processes. Therefore the mechanism of [[InterProcessCommunication]] should be used instead:

* <tt>InterProcessComm.open(ChannelSpec);</tt> to open a communication channel. It may create a shared-memory-access-object.
* <tt>InterProcessComm.receive(...);</tt>: Receive any data from another process. It may check the shared memory whether expected information are given. It is not specified which addresses and which information inside the shared memory are checked. The receive operation is a broadcast-receive. To specify a finer granularity in information-receiving, there should be more as one <tt>open(...)</tt>-operations which are associated to parts of information in the shared memory. The <tt>receive(...)</tt>-operation is more ''wait for event''-adequate as ''read memory''. But usual it is it, which are expected in a communication between processes. The user should rather think about ''I will use the shared memory'' but ''I have to get events from another process''.

* <tt>InterProcessComm.send(data, address);</tt>: it sets informations, maybe setting values in the shared memory

InterProcessCommunication

Admin — Sat, 05 Mar 2011 21:12:28 GMT

Admin: first

IPC

Os driver

Admin — Sat, 05 Mar 2011 21:04:33 GMT

Admin: first

The definition of the OSAL-level-interface for user applications is not valid for driver sources.

The sources for drivers are usual written for a defined platform. The driver are an application-special part of the Hardware-adaption-layer. The same driver software need not run under another platform without changes. The driver can be tested usual only in the original platform. Therefore for the driver level the [[OSAL]] - Operation System Application Layer-interfaces are not the only one access to the hardware and the operation system. It can be used and should be used where it is possible and rational, but the driver uses specials too.

OSAL

Admin — Sat, 05 Mar 2011 20:58:10 GMT

Admin: Protected "OSAL" ([edit=autoconfirmed] (indefinite) [move=autoconfirmed] (indefinite))

OSAL

Admin — Sat, 05 Mar 2011 20:57:40 GMT

Admin: /* Navigation */

Components of vishia-Java

Admin — Sun, 27 Feb 2011 07:06:32 GMT

Admin: Navigation

==Navigation==
* up: [[Main_Page]] / [[Component]]
* down: see chapters

==Overview==
vishia-Java is a tree of Java-files in the package-structure ''org/vishia/stuff''. All files are written by Hartmut Schorrig, www.vishia.org. They are used in some applications in profession too (with second license model). It is a conglomeration of different things, of course.

The usage of all files as jar-library if only a few files are needed - it isn't optimal:
* The usage as library will be proper, if an extrinsic application will use them as it is.
* If one of developers uses a component in another self-programmed application, it is self-evident to improve the used component with the challenges of the application. In that case the source should be present to check, change and improve.
* But on the other hand, if an extrinsic application should use that components proper, it should be well tested in a defined environment. A conglomeration can't be tested well enough.

Therefore that Java-sources are separated in some components. Any of the named component is available as a bazaar archive to work with sources. Any of this components are available as a download-file with some test environments as a application - or some test-Java-files exist.

This components are presented in the next chapters:

==srcJava_ZBNF==
* distribution on [[http://sf.net/projects/zbnf sf.net/projects/zbnf]]
* bazaar-archive on [[https://launchpad.net/zbnf/srcjava.zbnf launchpad.net/zbnf/srcjava.zbnf]]
* description, home-site on [[http://www.vishia.org/ZBNF www.vishia.org/ZBNF]]

Content of the distribution:
* The ZBNF-Parser with this Java-soruce is able to use discrete to convert plain-text but well-syntactical files into XML.
* The Java-sources includes a tool ''Header2Reflection'' which translates C/C++-headerfiles to C-files, which represents reflection-information about the data structures. It is used in a ''ReflectPro''-suite.
* A ''Zmake''-Tool is assiciated there. It converts simple make-prescripts to [[http://en.wikipedia.org/wiki/Apache_Ant ANT]]-make-files.

Further usage:
* The ZBNF is used in almost all applications of the author. It is because the applications translates some texts (for example Java2C), it needs config-files (GUI) etc.

Contains:
* A commandline calling argument preparer is included in the srcJava_ZBNF-package because it is the core-package of all applications.
* Some util-components are included.
there.
* Some XML-functionalities are included. Because the ZBNF-Parser outputs XML, a simple XML-Outputter is a core-part. A calling environment for XSLT, which can work with more as one input-XML-file, is contained there. But the XSLT-translator itself should be supplied by. SAXON is recommended. For the input preparing JDOM is used. Supplied-by-packages are not need while compiling, because there are symbolic-dynamic-linked using <tt>Class.forName("nameOfClass")</tt>.

Dependencies:
* This component has not any dependencies to any foreign component. Only standard-Java-classes are used.

==srcJava_vishiaXML==

links: TODO

Contains:
* Some functionality for documentation generation via XML.

Dependencies:

* This component needs SAXON and JDOM.

==srcJava_vishiaRun==

links: TODO

This component offers routines, which are nice to have in a longtime-running system. In opposite, some applications runs as task to translate something etc. If there are finished, the application is closed.

Contains:
* An interface to socket usage: This interface has the same concept as in C-language in the CRuntimeJavalike: [[InterProcessComm]].
* A reflect-target-engine. It allows to access to all data while running via the Java-Reflections. All data can visited, presented as time-track and changed (with policy).
* A MessageDispatcher which separates output messages (logs, able to use for embedded applications too).
* Access to binary data, which are described symbolic. It includes translation from C-language headerfiles for its structure.
* Some additional parts which are used especially if the Java-sources should be translated to C with [[Java2C]].

==srcJava_Java2C==
* distribution on [[http://sf.net/projects/zbnf sf.net/projects/java2c]]
* bazaar-archive on [[https://launchpad.net/java2c launchpad.net/java2c]]
* description, home-site on [[http://www.vishia.org/Java2C www.vishia.org/Java2C]]

Contains:
Sources of the translator

==srcJava_vishiaGUI==
links TODO

The appearance of a GUI is able to control with scripts.

Another aspect is: All widgets are placed on a fix position, but not organized in pixel, rather than in grid-units. The size of the grid can be changed in runtime for lesser or greater display (zoom).

The basic functionalities and a configurable executable are provided. A complex application with additional source of data to show and edit can be programmed in Java using this component as base. That user-program should not know details about graphic-programming systems. A widget is a widget, not a complex of GUI-calls of the basic graphic system.

The basic graphic system used is: SWT. Swing was used in the past, but should be established again. The goal is: Both systems can be used in several applications, without change of the users application. it is a adaption layer to the basic graphic system.

Components of vishia-Java

Admin — Sun, 27 Feb 2011 07:03:01 GMT

Admin: components: XML, GUI

==Overview==
vishia-Java is a tree of Java-files in the package-structure ''org/vishia/stuff''. All files are written by Hartmut Schorrig, www.vishia.org. They are used in some applications in profession too (with second license model). It is a conglomeration of different things, of course.

The usage of all files as jar-library if only a few files are needed - it isn't optimal:
* The usage as library will be proper, if an extrinsic application will use them as it is.
* If one of developers uses a component in another self-programmed application, it is self-evident to improve the used component with the challenges of the application. In that case the source should be present to check, change and improve.
* But on the other hand, if an extrinsic application should use that components proper, it should be well tested in a defined environment. A conglomeration can't be tested well enough.

Therefore that Java-sources are separated in some components. Any of the named component is available as a bazaar archive to work with sources. Any of this components are available as a download-file with some test environments as a application - or some test-Java-files exist.

This components are presented in the next chapters:

==srcJava_ZBNF==
* distribution on [[http://sf.net/projects/zbnf sf.net/projects/zbnf]]
* bazaar-archive on [[https://launchpad.net/zbnf/srcjava.zbnf launchpad.net/zbnf/srcjava.zbnf]]
* description, home-site on [[http://www.vishia.org/ZBNF www.vishia.org/ZBNF]]

Content of the distribution:
* The ZBNF-Parser with this Java-soruce is able to use discrete to convert plain-text but well-syntactical files into XML.
* The Java-sources includes a tool ''Header2Reflection'' which translates C/C++-headerfiles to C-files, which represents reflection-information about the data structures. It is used in a ''ReflectPro''-suite.
* A ''Zmake''-Tool is assiciated there. It converts simple make-prescripts to [[http://en.wikipedia.org/wiki/Apache_Ant ANT]]-make-files.

Further usage:
* The ZBNF is used in almost all applications of the author. It is because the applications translates some texts (for example Java2C), it needs config-files (GUI) etc.

Contains:
* A commandline calling argument preparer is included in the srcJava_ZBNF-package because it is the core-package of all applications.
* Some util-components are included.
there.
* Some XML-functionalities are included. Because the ZBNF-Parser outputs XML, a simple XML-Outputter is a core-part. A calling environment for XSLT, which can work with more as one input-XML-file, is contained there. But the XSLT-translator itself should be supplied by. SAXON is recommended. For the input preparing JDOM is used. Supplied-by-packages are not need while compiling, because there are symbolic-dynamic-linked using <tt>Class.forName("nameOfClass")</tt>.

Dependencies:
* This component has not any dependencies to any foreign component. Only standard-Java-classes are used.

==srcJava_vishiaXML==

links: TODO

Contains:
* Some functionality for documentation generation via XML.

Dependencies:

* This component needs SAXON and JDOM.

==srcJava_vishiaRun==

links: TODO

This component offers routines, which are nice to have in a longtime-running system. In opposite, some applications runs as task to translate something etc. If there are finished, the application is closed.

Contains:
* An interface to socket usage: This interface has the same concept as in C-language in the CRuntimeJavalike: [[InterProcessComm]].
* A reflect-target-engine. It allows to access to all data while running via the Java-Reflections. All data can visited, presented as time-track and changed (with policy).
* A MessageDispatcher which separates output messages (logs, able to use for embedded applications too).
* Access to binary data, which are described symbolic. It includes translation from C-language headerfiles for its structure.
* Some additional parts which are used especially if the Java-sources should be translated to C with [[Java2C]].

==srcJava_Java2C==
* distribution on [[http://sf.net/projects/zbnf sf.net/projects/java2c]]
* bazaar-archive on [[https://launchpad.net/java2c launchpad.net/java2c]]
* description, home-site on [[http://www.vishia.org/Java2C www.vishia.org/Java2C]]

Contains:
Sources of the translator

==srcJava_vishiaGUI==
links TODO

The appearance of a GUI is able to control with scripts.

Another aspect is: All widgets are placed on a fix position, but not organized in pixel, rather than in grid-units. The size of the grid can be changed in runtime for lesser or greater display (zoom).

The basic functionalities and a configurable executable are provided. A complex application with additional source of data to show and edit can be programmed in Java using this component as base. That user-program should not know details about graphic-programming systems. A widget is a widget, not a complex of GUI-calls of the basic graphic system.

The basic graphic system used is: SWT. Swing was used in the past, but should be established again. The goal is: Both systems can be used in several applications, without change of the users application. it is a adaption layer to the basic graphic system.

Components of vishia-Java

Admin — Sun, 27 Feb 2011 06:42:04 GMT

Admin: Protected "Components of vishia-Java" ([edit=autoconfirmed] (indefinite) [move=autoconfirmed] (indefinite))

Component

Admin — Sun, 27 Feb 2011 06:38:53 GMT

Admin: Criterion for Components: frequently changed parts without core functionality

==Navigation==
* up: [[Main_Page]]
* down: [[Components_of_vishia-Java]] [[Components_of_CRuntimeJavalike]]

==Components and modules, re-using==

A software should consist of more as one component. Each component should be able to describe, program and test independent of the application which uses it. A component may be able to use in several applications. Then it is reuseable.

Modules are the finer granularity inside components or inside the core of the application. Each module should be able to describe, program and test independently too. Modules may be one C/h-file or a package in Java or some related files.

A class in ObjectOrientation is the more finer granularity inside modules. A class in the C-programming is a logical coherence between one data structure and related subroutines. One class may be presented exactly with one source-file.

==Dependencies between components, modules, classes==

If another class is used inside a class, it depends on it. Formally it depends on the signature of the methods of the class. Really the functionality depends on the functionality of the called methods.

For a independent test of a class, module or component it may be necessary to abstract the functionality of the depending stuff. The behavior of the depending stuff should be replaced by a simulation or emulation.

There are '''horizontal and vertical dependencies''': If a class/module/component can be created, described and tested independent on another class/module/component, it is deeper in vertical or parallel in horizontal layer. If a class/module/component needs another one, it is above that in vertical layer. ''It needs'' means, in the real application it is associated to it and calls some methods from there. For the independently test all needed classes/modules/components may be able to replace.

===Interfaces as dependency-breaker===

There is a problem: Module_A needs some methods from Module_B and on the other hand Module_B needs some things from Module_A. Both modules are parallel in layer, but there are not able to develop and test independently.

Either the both modules are not two separated modules, the functionality should be combined in one module. - Or it should be separated using interfaces.

The ''interface'' is a language-element of Java. It defines methods with its signature, but without implementation. The description, "''what should the method do, which argument values are expectable, meaning of the return value''" belongs to the method anyway. In C++ interfaces are able to create in a similar kind as Java. It is a class with only virtual abstract methods and without any implementation:

class InterfaceExample { //C++-interface
virtual int aMethod(int arg) = 0;
};

====Classic C - Headerfiles as interface====

The classic C programming knows headerfiles, which ones play the role of interfaces: Function prototypes has the same appearance as a method definition in a Java-interface or a virtual abstract methods:

extern int aFunction(int arg);

The difference to Java and C++-virtual-methods is: It is static linked. There can be only one implementation in a executable, whereby in Java and C++ the interface can be implement by several classes which are instantiated independently. It is a ''dynamic link''.

But the principle of dependency-break is the same.

====Classic C- struct forward declaration as dependency break====

In C and C++ there is a nice possibility to prevent to many include-necessities:

struct TheType_t;

typedef struct Example_t{
struct TheType_t* pointer;
} Example;

Inside the Example-struct a pointer of TheType is need. But <tt>TheType</tt> itself may left unknown. It isn't necessary to know the type while compiling this struct. It is not necessary to include the typedef of <tt>TheType</tt>

If the pointer is used in the implementation (the C-file), then the type should be known. The implementation-File includes the definition of:

typedef struct TheType_t{
int someStuff;
}Thetype;

Now the compiler checks the matching of <tt>struct TheType_t</tt> to <tt>TheType</tt> with its given definition. The <tt>TheType_t</tt> is the tag-name of the struct where <tt>TheType</tt> is the really type name. The writing-style with <tt>_t</tt>-suffix is recommended and usual but not a fix rule.

The forward declaration of a pointer-type straightens a complex dependencies of header files. In Java there is not a adequate possibility. A Java-interface is the way of straighten still.

==Criterion for Components==
* Able to define and describe as entity.
* Able to test as entity.
* Dependencies of parts to other components: If any new part creates a new dependency to a foreign component, it should be realized as critical. Either the new dependency is desired, or the part should not be a part of this component.
* Conglomerate of several functionality: It is okay, if the modules doesn't need other components (see ''dependencies''). A component can contain a functionality, which is not need in the typical use-cases, but it is offered for special usages.
* Frequently changes in conglomerate parts: Any change in the sources of the component builds a new release of the whole component, which should be checked for relevance for all usages. Parts, which are frequently changed, but they are not a core functionality of the component, should be dissolved from the component therefore.
* Self-reliance: The same functionality should not scattered to several components. Only one component should be responsible to that functionality.

CRuntimeJavalike

Admin — Sun, 27 Feb 2011 06:28:38 GMT

Admin: Protected "CRuntimeJavalike" ([edit=autoconfirmed] (indefinite) [move=autoconfirmed] (indefinite))

==Navigation links==
TODO

==Content==
The CRuntimeJavalike-C-routines were created from 2004. The Reason: For embedded applications no proper basic functions are present. But in Java there is a well proper base system
* for all multithreading requirements (class java.lang.Thread, methods synchronized for Objects etc)
* for all Input/Output requirements (java.io)
* for Container, especially lock-free with atomicAccess (ConcurrentLinkedQueue etc)
* etc. etc.
The feeling for that concepts and using as interface for C-language seems a stable concept for basic-functions in C rather than the old-style basic functions like fprintf etc and rather than direct usage of the special offers of the underlying operation system. The last one prevents testing on PC or needs a special adaption and blocks re-using.

A next goal was the establishment of a Java2C-translator, which allows to write and test algorithm in Java and then translate to C-language. The CRuntimeJavalike-base-system replaces the functionality of the Java-basics for the embedded C-software.

Some more complex functionality of the CRuntimeJavalike is programmed in Java and translated to C. The pure C-Source-code should be able to use and understand well. But it should not be improved in C.

C++-usage: All functionality is provided in C. But there are wrappers for C++ to get a better calling style. The usage of C++ for embedded applications is recommended by me, if a subset is used. The whole slang of C++ may not so proper in my mind: C is more closed to machine code, it is known whats happen.

The CRuntimeJavalike-functions are not complex. They are no more complex as any hand-written functions for the same requests, which are present in many software. A user can include the whole sources and use step by step the ones or other function. There is a hierarchical systems from solitaire basic functions, functions which uses some OSAL-calls, and more complex functions. The usage prepares the flow-path to program more ObjectOriented till usage of Java in embedded.

==Related links==
* [[https://launchpad.net/jc Bazaar-Archive on launchpad.net]]

Main Page

Admin — Mon, 21 Feb 2011 07:19:34 GMT

Admin: Protected "Main Page" ([edit=autoconfirmed] (indefinite) [move=autoconfirmed] (indefinite))

==Java4C==
Goals:
* Using Java-programming language for embedded software in cooperation with C (and C++-) software.
* Using a ObjectOriented style of programming also in C!
* Using Java-like basic routines inclusive operation-system-calls.
* Using Java for program and test, and translate the sources to C.

===Why Java?===
Java is not only a language for internet applications. Java is a programming system for common usage. The first approach to develop Java in 1994 was: Creation of a portable language for embedded applications. Java is used in some embedded applications like mobil phones, routers. It is present with a ''JTRES'': ''Java Technology for Realtime Embedded Systems'' provided by companies like Sun/Oracle, Aicas, Aonix/Atego and others.

The Java-syntax for expressions is similar like C. Java is strong declarative, like C. The differences to C are:
* ObjectOrientation
* It is a Language of a new generation. The C-style of programming was born in 1970 with orientation to structured programming. Java was born in 1994.
* Java supports a better test of algorithms. If there are any errors for example in the addressing (indexing) of arrays, it is detected safely in runtime. The algorithms need not be tested step by step to prevent such errors. A paradigma ''compile 'n run'' can be used. The time for testing can be reduced drasticly without reducing the quality of software respectively more complex algorithms can be tested in the same time like simple algorithm in C or C++.

Java uses dynamic data. The approach of dynamic data helps to handle with variegated data in many threads in large applications. For example the String-processing needs dynamic memory. But it is also possible to handle with static data (allocated on startup). For example, String processing using a StringBuilder-instance and the CharSequence-interface can execute without allocation of memory. Static data are proper to use for embedded systems often.

===Why not C++?===
C++ is ObjectOriented and a modern programming language too. It is downward-compatible with C.

But the usual programming style in C++ divergates from the style in C. There are handled with dynamic memory in some basic classes, complex constructs using the template concept are usual. An ordinary C++-program can't be used for embedded programming often.

The disadvantages of the C-language: Unsafe pointer arithmetic, arbitrary casts, unchecked array addressing are all present in C++ too. C++ doesn't help for testing such errors like C.

==The key author of this site==

has experience in embedded programming since 1977, beginning with Assembler programming with the Z80-processor. I'm working for a company in germany in themes of embedded control. This site presents experiences independently of concretely job definitions.

==The mission of this site==

Exchange of experiences. You can take place on discussion. You can complement the text of the pages with your experience and knowledge.

==Guide through the site==

TODO
*Style of programming in C: ObjectOrientation, OSAL layer, re-using
*CRuntimeJavalike
*Java2C-translator

First page: [[os_types_def]].

Main Page

Admin — Sun, 20 Feb 2011 08:10:48 GMT

Admin:

==Java4C==
* Using Java-programming language for embedded software in cooperation with C (and C++-) software.
* Using a ObjectOriented style of programming also in C!
* Using Java-like basic routines inclusive operation-system-calls.
* Using Java for program and test, and translate the sources to C.

==Welcome to Your New Wiki==
A wiki is a powerful tool that allows multiple users to collaborate and share content rapidly. The best example of this is Wikipedia, which is powered by the exact same software that this wiki is!

==First Steps==
# An administrative user has already been created for you with all rights over this wiki. You should first [[Special:UserLogin|log in]] using '''Username:''' admin '''Password:''' changeme
# Click on [[Special:Preferences|my preferences]] and change the admin password. Critical: If you don't do this, other users can take over your wiki.
# Click on the Control Panel link under "editthis.info tools" in on the left hand side of this page. From here you can set the Logo Image for your wiki that appears in the upper left of all pages.

==Optional Secondary Steps==
# Add your wiki to the [http://editthis.info/wiki/Categorized_Wiki_List Categorized List of Wikis]
# Promote your wiki by posting to your favorite social networks
# Create another user with a more personalized username (first log out, then click create an account).
# Join the [http://groups.google.com/group/editthisinfo EditThis.info News Group]
# Edit this page and replace it's content with something more interesting for new visitors.
# Read [http://editthis.info/wiki/How_to_make_a_successful_wiki How to make a successful wiki]
# Read the [http://editthis.info/wiki/Help:Contents Help Page]

MediaWiki:Sidebar

Admin — Mon, 14 Dec 2009 16:08:20 GMT

Main Page

Admin — Mon, 14 Dec 2009 16:07:03 GMT

Admin: Created page with '==Welcome to Your New Wiki== A wiki is a powerful tool that allows multiple users to collaborate and share content rapidly. The best example of this is Wikipedia, which is powere…'

==Welcome to Your New Wiki==
A wiki is a powerful tool that allows multiple users to collaborate and share content rapidly. The best example of this is Wikipedia, which is powered by the exact same software that this wiki is!

==First Steps==
# An administrative user has already been created for you with all rights over this wiki. You should first [[Special:UserLogin|log in]] using '''Username:''' admin '''Password:''' changeme
# Click on [[Special:Preferences|my preferences]] and change the admin password. Critical: If you don't do this, other users can take over your wiki.
# Click on the Control Panel link under "editthis.info tools" in on the left hand side of this page. From here you can set the Logo Image for your wiki that appears in the upper left of all pages.

==Optional Secondary Steps==
# Add your wiki to the [http://editthis.info/wiki/Categorized_Wiki_List Categorized List of Wikis]
# Promote your wiki by posting to your favorite social networks
# Create another user with a more personalized username (first log out, then click create an account).
# Join the [http://groups.google.com/group/editthisinfo EditThis.info News Group]
# Edit this page and replace it's content with something more interesting for new visitors.
# Read [http://editthis.info/wiki/How_to_make_a_successful_wiki How to make a successful wiki]
# Read the [http://editthis.info/wiki/Help:Contents Help Page]