The OnBoard Suite (Compiler Developer's) FAQ v1.1
Note. A pair of overlapping OnBoard Suite communities exist: one for development of the OnBoard Suite and one for using the OnBoard Suite. This FAQ covers the development of the OnBoard Suite.

Copyright 2002,2003 Wade Guthrie. Permission is granted to copy and redistribute this document so long as it is unmodified (including the section that describes where to get this document for free) and the copyright remains in-tact. This should sort-of be copyrighted by the SourceForge OnBoard Suite group since much of this has been gleaned from that discussion group but I don't know if that would be legally binding. The purpose of the copyright, anyway, is just to make sure that noone charges for the information, such as it is, that we're giving away for free.

Disclaimer. The information in this FAQ is a compilation from members of the OnBoard Suite group and various other sources including the internet. The author/maintainer does not guarantee any of the information found in this FAQ. Use this FAQ AT YOUR OWN RISK and with your own judgement (in fact, this is pretty good advice for all the information found on the internet).

Location. The latest version of this document can be obtained (for free) from the OnBC SourceForge homepage. If you have any questions, comments, corrections or suggestions, please don't hesitate to send them to

Thanks. A special thanks goes to several people who have contributed to this document. The list (in alphabetical order) can be found at the end of this document. If I've left anyone out, please contact me at the above address.

Changes. The following changes have been made to get to the versions that are described.




1. Introduction 2. What do I need to do to help develop OnBoardC? 3. How do I...? 4. Thanks!

1. Introduction

What's The OnBoard Suite?

The OnBoard Suite (OnBSuite) is a wonderful C IDE written by Roger Lawrence of Individeo. It runs on, as well as builds code for, the Palm handheld platform.

Where can I learn more about the OnBoard Suite?

The OnBSuite main page is hosted by the wonderful people at SourceForge.

There is a very active user community for the OnBoard Suite on Yahoo.

For the more industrious, there is also an active compiler development community for the OnBoard Suite on SourceForge.

2. What do I need to do to help develop OnBoardC?

Read the OnBoard Suite development charter.

When the OnBoard Suite SourceForge project was started, a bunch of us thought it'd be good if we decided on a standard way of doing things. The results of that discussion can be found in the OnBoard Suite development charter. Please read it before doing anything to the source code.

Join the SourceForge OnBoard Suite group.

There're two parts to joining the SourceForge OnBoard Suite group.

First, you need a SourceForge ID. To do this, go to the SourceForge site and click the 'New User via SSL' link at the top-left of the page. Then, fill out the form and click 'register'. If everything went well, SourceForge will confirm that you have a new account.

Once you are registered (and have received confirmation from SourceForge), email your 'Login Name' to one of the Project Admins. Currently, those are (in alphabetical order) David Beers and Steve Little. That person will add you to the list and -- poof -- you're an OnBoard Suite compiler developer.

Load and install the tools.

SourceForge has its own set of tools for development. The SourceForge site has a bunch of documents that describe which tools you need, where to get them, and how to download and install them. Which docs you use depends on which OS you'll be using:

Read the OnBoard Suite development charter (again).

There's a bunch about the process of developing the OnBoard Suite in the charter, so give it another read. That'll be easier that cutting from the charter and pasting here -- especially as the charter evolves over time.

Use the tools!

Once you get everything setup, you'll want to check the source out of CVS.

Start by running Pageant (from the SSH tools -- Windows users may have to double-click on the icon in the task tray), click 'Add Key' button and click the key you generated in the PuttyGen phase of tools installation.

Next, bring-up CVS and checkout a module (on WinCVS, click 'create' on the menubar and click 'checkout module...' on the menu). The module name and path on the server is 'OnBoardC' (without the quotes).

3. How do I...?

...Branch off the main CVS trunk?

Start by creating the branch, note this only creates the branch in the repository and does not change your local source.
Command-Line WinCVS
$ cvs tag -b C001 OnBoard OnBoardC
Here, I had to select SrcEdit in the left pane. Then I clicked on 'Modify', 'Create a branch on selection'. I typed S012 as the branch name (C001 for the sample by Johnny).

I am PoC for task C001 and needed a branch as the charter says to make this modification, so I branched OnBoard and OnBoardC since the task was for the assembler and compiler portions of the project.

That command produced output like this:

cvs server: Tagging OnBoard
T OnBoard/OnBoard.FNP
T OnBoard/OnBoard.mcp
T OnBoard/OnBoard.old.mcp
cvs server: Tagging OnBoard/OnBoard Data
T OnBoard/OnBoard Data/CW Settings.stw
T OnBoard/OnBoard Data/CWSettingsWindows.stg
cvs server: Tagging OnBoard/OnBoard Data/OnBoard.prc
T OnBoard/OnBoard Data/OnBoard.prc/TargetDataWindows.tdt
cvs server: Tagging OnBoard/Resource.frk
T OnBoard/Resource.frk/OnBoard.tmp
T OnBoard/Resource.frk/PalmPilotApp.tmp
cvs server: Tagging OnBoard/Src
T OnBoard/Src/Makefile
T OnBoard/Src/Math.c
T OnBoard/Src/OnBoard.c
T OnBoard/Src/OnBoard.h
T OnBoard/Src/OnBoard_res.h

NOW with:
Command-Line WinCVS
$ cvs status -v
The status is found when selecting on a file, 'Query', 'Status selection'.

you can see something like this:

File: onBoard_res.h     Status: Up-to-date

   Working revision:
   Repository revision:
   Sticky Tag:          (none)
   Sticky Date:         (none)
   Sticky Options:      (none)

   Existing Tags:
        C001                            (branch:
        import                          (revision:
        cvs                             (branch: 1.1.1)

You can see your branch tag indicated in the repository. Now you need to get what CVS folks call sticky to your branch. The source on your system is the head revision, so you currently are not sticky to any revision/branch as the status shows via the Sticky Tag field.

I wanted to have my branch and head revision on my machine at the same time, so I needed to checkout a new working copy and then update it to the branch. If you don't care about that then just skip the next step, goto the cvs update step.

I had my head revision in ~/dev/onboardc/, I made a directory in which to put the branched code ~/dev/onboardc/c001/. The head revision was represented by ~/dev/onboardc/OnBoardC and the new branch revision is represented on my system ~/dev/onboardc/c001/OnBoardC. I hope this makes sense.

So I did this:
Command-Line WinCVS
$ cvs -z3 co OnBoardC 
No idea how to do this :(

I made a second copy by copy/pasting the SrcEdit dir and renaming it into S012.

Which resulted in this:

cvs server: Updating OnBoardC
U OnBoardC/checkoutlist
U OnBoardC/syncmail
cvs server: Updating OnBoardC/Old Dox
U OnBoardC/Old Dox/Error.gif

Now time to get sticky to my branch revision. This is the update step you could have skipped to. So I changed directory to ~/dev/onboardc/c001/OnBoardC and did the following.

Get Sticky to branch:
Command-Line WinCVS
$ cvs up -P -r C001
Select the S012 dir in the left pane, and 'Modify', 'Update selection','Sticky options',check the 'Retrieve rev/tag/branch', type S012 in the field. Click OK.

cvs server: Updating .
cvs server: checkoutlist is no longer in the repository
cvs server: syncmail is no longer in the repository
cvs server: Updating Old Dox
cvs server: Old Dox/Error.gif is no longer in the repository
cvs server: Old Dox/trans_1x1.gif is no longer in the repository
cvs server: Updating OnBoard
cvs server: Updating OnBoard/GCC
cvs server: Updating OnBoard/OnBoard Data
cvs server: Updating OnBoard/OnBoard Data/OnBoard.prc

Now I was sticky to my branch meaning I now had a working copy of the source branced, so I could make changes and not bother the head revision.

To see the branch do this:
Command-Line WinCVS
$ cvs status -v
To be sure whether you can commit a file in the S012 branch, select it and Query status selection. If you see "sticky tag: S012" then you're sure that the commits will take place in the branch. Else, you have to re-do an update on the particular file.
And you'll see:

File: compile.c         Status: Up-to-date

   Working revision:    1.5
   Repository revision: 1.5
   Sticky Tag:          C001 (branch: 1.5.2)
   Sticky Date:         (none)
   Sticky Options:      (none)

   Existing Tags:
        C001                            (branch: 1.5.2)
        import                          (revision:
        cvs                             (branch: 1.1.1)

Now you can see this code is Sticky to the branch. Now from here just edit files and commit them as normal. They will be commited to your branch. You can use the commands just like normal.

When you have completed all the changes you want and are ready to commit them to the head revision then you need to do a merge. I will send an email if desired on how to do the merge back into the head revison, once you have the ROGER of course.

The reason for the sticky ness is so that all the changes you commit are against the revsion you are sticky to and not someonething else, or the head revision. Once we release we should tag and make bug fixes against that revision merging those in later. So, you would get sticky to the release. This can also be used for experimental code, etc.

...Join a branch back into the main trunk?

Since I was happy with my changes for half of task C001, the OnBOard/assembler portion of the task, I requested the Roger and once it was passed I went about the following. For the GUI cvs users this should be close, or similar.

1.) Changed my current directory to my head revision directory, or where I had it checked out. This is the place I want the merge to happen. For me it was:


2.) Now perform the merge, i.e. merging the changes in C001 to the head revision which looks like:

$ cvs up -j C001
cvs server: Updating .
U OnBoard.mcp
cvs server: scheduling OnBoard.old.mcp for removal
cvs server: Updating OnBoard Data
cvs server: scheduling OnBoard Data/CW Settings.stw for removal cvs
server: scheduling OnBoard Data/CWSettingsWindows.stg for removal cvs
server: Updating OnBoard Data/OnBoard.prc cvs server: scheduling OnBoard
Data/OnBoard.prc/TargetDataWindows.tdt for removal cvs server: Updating
Resource.frk cvs server: scheduling Resource.frk/OnBoard.tmp for removal
cvs server: scheduling Resource.frk/PalmPilotApp.tmp for removal cvs
server: Updating Src RCS file:
retrieving revision 1.6
retrieving revision
Merging differences between 1.6 and into OnBoard.c
RCS file: /cvsroot/onboardc/OnBoardC/OnBoard/Src/debug.c,v
retrieving revision 1.4
retrieving revision
Merging differences between 1.4 and into debug.c
RCS file: /cvsroot/onboardc/OnBoardC/OnBoard/Src/debugTypes.h,v
retrieving revision 1.2
retrieving revision
Merging differences between 1.2 and into debugTypes.h RCS file:
retrieving revision 1.6
retrieving revision
Merging differences between 1.6 and into sourceFiles.c cvs
server: Updating Src/Pilrc RCS file:
retrieving revision 1.3
retrieving revision
Merging differences between 1.3 and into OnBoard.rcp cvs server:
Updating Src/RESOURCE.FRK cvs server: scheduling
Src/RESOURCE.FRK/OnBoard.rsrc for removal cvs server: scheduling
Src/RESOURCE.FRK/onBoard_res.h for removal

2. CONT) Note the files scheduled for removal and the revision merges.

3.) Make sure everything still works, just as a sanity check before the commit. Note that the merge is only in my local directory and not on the server yet, not until I commit. So I cd'd to the Src dir and built the project.

$ cd Src/
$ make
m68k-palmos-gcc -O2 -Wall -g   -c -o debug.o debug.c
m68k-palmos-gcc -O2 -Wall -g   -c -o OnBoard.o OnBoard.c
m68k-palmos-gcc -O2 -Wall -g   -c -o sourceFiles.o sourceFiles.c
m68k-palmos-multigen Pilrc/OnBoard.def
m68k-palmos-as   -o OnBoard-sections.o OnBoard-sections.s
m68k-palmos-gcc -O2 -Wall -g  -o OnBoard OnBoard-sections.o
OnBoard-sections.ld debug.o OnBoard.o sourceFiles.o pilrc -I Pilrc/ -q
Pilrc/OnBoard.rcp Pilrc/ && touch OnBoard.rcp_bin PilRC v2.9
  Copyright 1997-1999 Wes Cherry   (
  Copyright 2000-2001 Aaron Ardiri (

Generating 68K resources from 'Pilrc/OnBoard.rcp'.
build-prc -o OnBoard.prc -t appl -n "OnBoard" -c "OnBA"
Pilrc/OnBoard.def OnBoard Pilrc/*.bin

$ make clean
rm -f *.o *.[pg]rc Pilrc/*.bin *-sections.* OnBoard *~ OnBoard.rcp_bin

$ cd ..

4.) Verify there were no merge conflicts, the build did not fail in my case, and examing the output of the cvs up -j command showed no merge conflicts. Cvs will put some text into your files where it could not perform a merge safely and cvs depends on you to fix that before commiting. The code should not build if you have merge conflicts. Also, cvs will backup the changes locally by putting files with something like this ".#xyz.c1.1" It is easy to identify merge conflicts in a file, but you have to fix them when they occur and do it before you commit the changes. In this case I had no conflicts as anticipated, so I was ready to commit my work on the assembler.

$ cvs com -m "Merged OnBoard portion of C001"
cvs commit: Examining .
cvs commit: Examining OnBoard Data
cvs commit: Examining OnBoard Data/OnBoard.prc
cvs commit: Examining Resource.frk
cvs commit: Examining Src
cvs commit: Examining Src/Pilrc
cvs commit: Examining Src/RESOURCE.FRK
Checking in OnBoard.mcp;
/cvsroot/onboardc/OnBoardC/OnBoard/OnBoard.mcp,v  <--  OnBoard.mcp new
revision: 1.3; previous revision: 1.2 done Removing OnBoard.old.mcp;
/cvsroot/onboardc/OnBoardC/OnBoard/OnBoard.old.mcp,v  <--
OnBoard.old.mcp new revision: delete; previous revision: done
Removing OnBoard Data/CW Settings.stw;
/cvsroot/onboardc/OnBoardC/OnBoard/OnBoard Data/CW Settings.stw,v  <--
CW Settings.stw new revision: delete; previous revision: done
Removing OnBoard Data/CWSettingsWindows.stg;
/cvsroot/onboardc/OnBoardC/OnBoard/OnBoard Data/CWSettingsWindows.stg,v
<--  CWSettingsWindows.stg new revision: delete; previous revision: 1.2
done Removing OnBoard Data/OnBoard.prc/TargetDataWindows.tdt;
Data/OnBoard.prc/TargetDataWindows.tdt,v  <--  TargetDataWindows.tdt new
revision: delete; previous revision: 1.2 done Removing
/cvsroot/onboardc/OnBoardC/OnBoard/Resource.frk/OnBoard.tmp,v  <--
OnBoard.tmp new revision: delete; previous revision: done
Removing Resource.frk/PalmPilotApp.tmp;
/cvsroot/onboardc/OnBoardC/OnBoard/Resource.frk/PalmPilotApp.tmp,v  <--
PalmPilotApp.tmp new revision: delete; previous revision: done
Checking in Src/OnBoard.c;
/cvsroot/onboardc/OnBoardC/OnBoard/Src/OnBoard.c,v  <--  OnBoard.c new
revision: 1.7; previous revision: 1.6 done Checking in Src/debug.c;
/cvsroot/onboardc/OnBoardC/OnBoard/Src/debug.c,v  <--  debug.c new
revision: 1.5; previous revision: 1.4 done Checking in Src/debugTypes.h;
/cvsroot/onboardc/OnBoardC/OnBoard/Src/debugTypes.h,v  <--  debugTypes.h
new revision: 1.3; previous revision: 1.2 done Checking in
/cvsroot/onboardc/OnBoardC/OnBoard/Src/sourceFiles.c,v  <--
sourceFiles.c new revision: 1.7; previous revision: 1.6 done Checking in
/cvsroot/onboardc/OnBoardC/OnBoard/Src/Pilrc/OnBoard.rcp,v  <--
OnBoard.rcp new revision: 1.4; previous revision: 1.3 done Removing
/cvsroot/onboardc/OnBoardC/OnBoard/Src/RESOURCE.FRK/OnBoard.rsrc,v  <--
OnBoard.rsrc new revision: delete; previous revision: done
Removing Src/RESOURCE.FRK/onBoard_res.h;
/cvsroot/onboardc/OnBoardC/OnBoard/Src/RESOURCE.FRK/onBoard_res.h,v  <--
onBoard_res.h new revision: delete; previous revision: done

5.) As you can see the merge and commit where successful and now my local copy has my task changes. One last thing is to update my head revision using the -P flag which prunes empty directories. Many of the CodeWarrior directories are generated and not needed in the revision control system. I took extra care to test this out. Once I was satisfied I removed the files; However, I cannot remove empty directories as cvs provides no facility to do this. Not a big deal, just do your updates with prune empties. If one of the admins feels froggy we could nake a request to the SourceForge admins to manual take care of the empties if desired.

$ cvs up -P
cvs server: Updating .
cvs server: Updating OnBoard Data
cvs server: Updating OnBoard Data/OnBoard.prc
cvs server: Updating Resource.frk
cvs server: Updating Src
cvs server: Updating Src/Pilrc
cvs server: Updating Src/RESOURCE.FRK

That's it, that is all there is. One thing you can do is merge the main trunk into your branch prior to your merging back the main trunk. WHY? The reason why is so you can take care of the merge conflicts in the branch rather than the main trunck. If the main trunck changes infrequently then this is agood way to go if you know it has changed and you want to incorporate those changes in your branch. If the main truck changed frequently then there is no point in doing this, just merge your changes in. I will be doing this for the other half of Task C001 as I know OnBoardC was slightly changed after I branched the code. I would highly recommend keeping it simple and merging your branch back into the main truck, but I just wanted to point out that cvs supports merging in many ways, two of which I described here.

4. Thanks

I'm going to try to get everyone. If you contributed or know someone who did that's not in here, please let me know.
	Keithen and Roger at
	"davidsvisor" <;
	"Guillaume CLEMENT" <ndovchipyggrasil@ya...>
	"John P. Pywtorak" <jpywtora@ca...>