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 wade@adventure101.com.
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.
v1.1
v1.0
1. IntroductionTABLE OF CONTENTS
1. Introduction
What's The OnBoard Suite?
Where can I learn more about the OnBoard Suite?
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.
Read the OnBoard Suite development charter.
Join 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.
Read the OnBoard Suite development charter (again).
Use the tools!
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).
...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: 1.1.1.1
Repository revision: 1.1.1.1
/cvsroot/onboardc/OnBoardC/OnBoard/Src/...
Sticky Tag: (none)
Sticky Date: (none)
Sticky Options: (none)
Existing Tags:
C001 (branch: 1.1.1.1.2)
import (revision: 1.1.1.1)
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 -d:ext:jpywtora@cvs.onboardc.sourceforge.net:/cvsroot/onboardc 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. |
===================================================================
File: compile.c Status: Up-to-date
Working revision: 1.5
Repository revision: 1.5
/cvsroot/onboardc/OnBoardC/OnBoardC/Src/compi
Sticky Tag: C001 (branch: 1.5.2)
Sticky Date: (none)
Sticky Options: (none)
Existing Tags:
C001 (branch: 1.5.2)
import (revision: 1.1.1.1)
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:
~/dev/palm/onboardc/OnBoardC/OnBoard
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: /cvsroot/onboardc/OnBoardC/OnBoard/Src/OnBoard.c,v retrieving revision 1.6 retrieving revision 1.6.2.1 Merging differences between 1.6 and 1.6.2.1 into OnBoard.c RCS file: /cvsroot/onboardc/OnBoardC/OnBoard/Src/debug.c,v retrieving revision 1.4 retrieving revision 1.4.2.1 Merging differences between 1.4 and 1.4.2.1 into debug.c RCS file: /cvsroot/onboardc/OnBoardC/OnBoard/Src/debugTypes.h,v retrieving revision 1.2 retrieving revision 1.2.2.1 Merging differences between 1.2 and 1.2.2.1 into debugTypes.h RCS file: /cvsroot/onboardc/OnBoardC/OnBoard/Src/sourceFiles.c,v retrieving revision 1.6 retrieving revision 1.6.2.1 Merging differences between 1.6 and 1.6.2.1 into sourceFiles.c cvs server: Updating Src/Pilrc RCS file: /cvsroot/onboardc/OnBoardC/OnBoard/Src/Pilrc/OnBoard.rcp,v retrieving revision 1.3 retrieving revision 1.3.2.1 Merging differences between 1.3 and 1.3.2.1 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.
~/dev/palm/onboardc/OnBoardC/OnBoard $ 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 (wesc@ricochet.net) Copyright 2000-2001 Aaron Ardiri (aaron@ardiri.com) 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 .. to ~/dev/palm/onboardc/OnBoardC/OnBoard
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: 1.1.1.1 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: 1.1.1.1 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; /cvsroot/onboardc/OnBoardC/OnBoard/OnBoard Data/OnBoard.prc/TargetDataWindows.tdt,v <-- TargetDataWindows.tdt new revision: delete; previous revision: 1.2 done Removing Resource.frk/OnBoard.tmp; /cvsroot/onboardc/OnBoardC/OnBoard/Resource.frk/OnBoard.tmp,v <-- OnBoard.tmp new revision: delete; previous revision: 1.1.1.1 done Removing Resource.frk/PalmPilotApp.tmp; /cvsroot/onboardc/OnBoardC/OnBoard/Resource.frk/PalmPilotApp.tmp,v <-- PalmPilotApp.tmp new revision: delete; previous revision: 1.1.1.1 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 Src/sourceFiles.c; /cvsroot/onboardc/OnBoardC/OnBoard/Src/sourceFiles.c,v <-- sourceFiles.c new revision: 1.7; previous revision: 1.6 done Checking in Src/Pilrc/OnBoard.rcp; /cvsroot/onboardc/OnBoardC/OnBoard/Src/Pilrc/OnBoard.rcp,v <-- OnBoard.rcp new revision: 1.4; previous revision: 1.3 done Removing Src/RESOURCE.FRK/OnBoard.rsrc; /cvsroot/onboardc/OnBoardC/OnBoard/Src/RESOURCE.FRK/OnBoard.rsrc,v <-- OnBoard.rsrc new revision: delete; previous revision: 1.1.1.1 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: 1.1.1.1 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.
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.4. Thanks
Keithen and Roger at individeo.net "davidsvisor" <david@xp...gt; "Guillaume CLEMENT" <ndovchipyggrasil@ya...> "John P. Pywtorak" <jpywtora@ca...>