|Marathon - The SQL Tool for Firebird & InterBase
On this page you will find informations and instructions on how-to setup your environment when you want to contribute to the Marathon project. Marathon has come a long way and it was the first commercial GUI for InterBase databases. It was created and supported for a long time by Patrick O'Keeffe and his company Gimbal Software Service (GSS). In June, 2001 Marathon was made an Open Source project using the Mozilla Public License (MPL) and since this time it has been gone through some major code revise to make the Open Source development possible, easier and more transparent.
Here is the original text from Patrick regarding his decision to make Marathon an Open Source product:
We have decided to Open Source Marathon for a number of reasons:
If you have any questions or concerns, or wish to contribute to this project in any way, don't hesitate to contact me at firstname.lastname@example.org
- In order to provide a quality, best-of-breed product we found that the time we had to commit to Marathon was too much especially considering Marathon is not my full time job and we are both now full time parents.
- We felt that we weren't being fair to ourselves or our little boy by pursuing this any further.
- In addition we also felt that if we just closed up shop we were also not being fair to the customers and resellers that have supported us over the last three years.
Because Marathon is now Open Source, the project is always in search of new supporters and helpers in different positions. So if you want to help you can look through our task, bug and feature tracker to get an idea what needs to be done. If you want to help with programming, you don't need CVS access for your first contributions. It is enough to submit your patches in the patch tracker or you can send them directly to me. If you later want to become an active member with full CVS access, you can request to be added to the list of active developers. When you want to support us but don't know about Delphi, you can help the project with web site creation or working on documentation (very important but often underrated). Feel free to contact me if you have any questions.
Because Marathon is hosted on SourceForge, we have a wide range of functionality available despite simple CVS access. Here is a short description of these services and how they are used by the GMarathon project:
- CVS - The most important benefit of hosting Marathon at SourceForge is of course the CVS access. For more informations about CVS and SSH please read the documentation section at SourceForge or take a look here.
- Files - Here you will find all releases of the GMarathon team. We will make binaries and sourcecode of every release available. If you are looking for Snapshot builds, please have a look here.
- News - Any informations about new releases, important changes on the sourcecode, etc. are made public here.
- Tracker - Bug, Feature, Support and Patch tracker are available here. If you post to any of them make sure you provide as much information as possible, we will then take care of your problem ASAP. Patch Tracker: If you submit a patch please include a complete describtion of you changes or a CVS diff.
- Forums - Feel free to post your problems, comments or critics to the forums. The developer forum is only available to registered developers and should be used to discuss programming issues.
- Mailing Lists - If you don't want to use the web-based forum, just subscribe and send an e-mail.
- Tasks - Here you can see what we plan and what still needs to be done. If you think a new task should be established please ask in the forums and I will setup one.
- Docs - Additional documentation can be found here.
- Surveys - From time to time surveys will be launched to vote for new features or the direction the project is moving.
As an active Marathon coder you will need the following tools:
SourceForge CVS and SSH setup for developers:
- Delphi Professional 5, 6 or Enterprise Edition 5, 6. I don't think you can use the Open Edition or any earlier version of Delphi but if you can make Marathon compile with it please let me know.
Download and install your favorite CVS utility. For Windows I recommend to use the command line CVS tool (see the section beyond). There is also a GUI Tool called CvsGUI available. For Linux you don't need to download any additional software because CVS support should be included in your distribution.
- If you only want to check-out and don't want to commit changes, you only need anonymous access:
"cvs -d:pserver:email@example.com:/cvsroot/gmarathon login"
and after you have successfully logged in use
"cvs -z3 -d:pserver:firstname.lastname@example.org:/cvsroot/gmarathon co modulename".
to check out the sourcecode in your local folder.
Replace "modulename" with "oldsrc" for the old Marathon 1.5 and Marathon 2.0 stuff or "gmarathon" for the new source repository.
- If you have write access then you have to use the following command:
"cvs -z3 -d:ext:email@example.com:/cvsroot/gmarathon co modulename"
Keep in mind that you need SSH access and that you must be a member of the "gmarathon" project (please ask Patrick O'Keeffe or me(Tilo Muetze) to get added to the developers list) when you later want to commit changes. Also please read the paragraph CVS - OS Specific Information on how to set-up and configure CVS and SSH access on Sourceforge.
Replace "modulename" with "oldsrc" for the old Marathon 1.5 and Marathon 2.0 stuff or "gmarathon" for the new source repository.
Here is a step-by-step description which should help you setting up your CVS and SSH environment:
- Download the CVS command line distribution and extract it to "c:\work\CVS".
- Download SSH command line package and extract it to "c:\work\SSH".
- Download "PuTTY.exe" and "PuTTYgen.exe" and put both in the folder "c:\work\SSH".
- Use the command line to create the folder ".ssh" in "c:\work". This folder is used by SSH to store your keys in.
- Now add "c:\work\CVS" and "c:\work\SSH" to your PATH environment variable. In Win9x environments add it to "c:\autoexec.bat", in Windows NT, 2000 and XP use the "System Properties" - "Environment" applet.
- Add these additional environment variables:
- CVSROOTfirstname.lastname@example.org:/cvsroot/gmarathon (replace "your_sourceforge_username" with your actual SourceForge username)
- USERNAME=your_sourceforge_username (replace "your_sourceforge_username" with your actual SourceForge username)
- Now you need to create an "\etc" directory on the same drive you set your HOME directory to. In our case the folder: "c:\etc".
- Create a text file in this folder called "passwd" (not "password"!) with the following line: "your_sourceforge_username:x:1:10:SourceForge:c:/work/:c:/winnt/system32/cmd.exe" (Replace "your_sourceforge_username" with you actual SourceForge username and if you are on Win9x replace "c:/winnt/system32/cmd.exe" with "c:/windows/command.com").
- Restart your computer so that the environment variables can take place.
- Run "c:\work\SSH\PuTTYgen.exe" and create yourself a SSH keypair(If you enter a passphrase you have higher security but you also need to enter this phrase every time you do something with CVS, so I recommend let passphrase empty). Now save the public key as "c:\work\.ssh\identity.pub" and your private key as "c:\work\.ssh\identity".
- Now you can test your connection to SourceForge by opening the command line and executing the following command: "ssh -l your_sourceforge_username gmarathon.sourceforge.net" (replace "your_sourceforge_username" with your actual SourceForge username).
- Accept the key from SourceForge, and when prompted, enter your SourceForge password. After that enter "exit" to close the SSH connection.
- On your user account page at SourceForge, you should find a place to upload your SSH public key. Copy the content of the file "identity.pub" into the text entry box on the page -- be sure not to add any line breaks or it will not work.
- After the requisite 6 hour wait, you should be able to use CVS with SSH without using your password.
- After all these steps you should be able to do via the command line a: "cvs co gmarathon". This should check-out the module "gmarathon" to the current folder.
For further reading about CVS usage I recommend: Open Source Development with CVS by Karl Fogel.
Required third-party components:
Here you will find informations about the Delphi packages and components that you need to successfully compile Marathon.
- We start with the third party packages, which are not included in CVS. Please download and install them:
- The current CVS state of Marathon uses IB Objects 4.2H. If you don't have this version or you never had IB Objects before, just drop me an E-Mail asking for it. Please also CC this E-Mail to Jason Wharton, the author of IB Objects, because else I can't send you the files, due to IB Objects is without cost but not free for Marathon contributors. This means that there is no cost obligation, but you are required to register your usage of IB Objects and agree to the terms of the Trustware License which IB Objects uses.
- Synedit 20011025-CVS, for installation instructions please consult the Synedit website or the included documentation.
- Toolbar 2000 2.0.13, for installation instructions please consult the Toolbar 2000 website or the included documentation.
- rmControls 1.91, for installation instructions please consult the included documentation.
- Virtual TreeView 3.2.1, for installation instructions please consult the Virtual TreeView website or the included documentation.
- TPagePrinter 2.0 (with Marathon specific bug fixes), install in Delphi as a component using "PgPrnReg.pas"
- TDataSetPrint 1.23 (with Marathon specific bug fixes), install in Delphi as a component using "DSprint.pas"
- THexEditor 1.16 (with Marathon specific bug fixes), install in Delphi as a component using "Hexeditor.pas"
- The following components and packages are included in CVS module "gmarathon", in the "lib" directory, so you don't need to download them here:
- Marathon own package, SyntaxMemoWithStuff2("SyntaxMemoWithStuff2\SyntaxMemoWithStuff2Package.dpk")
- Marathon own component, TDBPanelEdit("Other\adbpedit.pas")
- Marathon own component, TCloseUpCustomComboBox("Other\CloseUpCombo.pas")
- Marathon own component, TDiagramTree("Other\DiagramTree.pas")
- Marathon own component, TIBPerformanceMonitor("Other\IBPerformanceMonitor.pas")
- Marathon own component, TMarathonColorGrid("Other\NewColorGrd.pas")
- Modified FreePascal units("Other\xmlread.pas", "Other\xmlwrite.pas", "Other\dom.pas")
If you have problems setting up any of these packages or components please post it in the discussion forums or try to contact me directly and I will try to help you.
After you are finished with the package and component installations you should be able to compile the checked-out sourcecode with no restrictions when you are using Delphi 6 of course. If you are using Delphi 5 there is a problem with properties which are exclusively available in Delphi 6. Here is a list of those properties:
So if you are using Delphi 5 please download:
- Marathon Delphi Tools from Carlos Macao which are specialized for this task. This tool works class-sensitive, e.g. you can specify that it only removes the property TabIndex from all TPageControl objects.
- Delphi property remover from Andrei Kireev. Warning: This tool removes all TabIndex property entries, regardless if the component is e.g. a TPageControl or a TNotebook.
Both programs make sure that all mentioned properties are deleted before you actually start developing, else you will get "invalid property" and runtime errors. Remember that you have to do this after every checkout via "cvs update gmarathon".
Marathon uses Want - A Delphi Friendly Build Tool from Juanco Anez for building. This step was necessary because Borland make-tools are very crude and incomplete whereas Want is much more powerful and flexible. Also we needed a simple tool which helps us generating daily binary and sourcecode snapshots. Here is a brief description:
- Download and install Want. Make sure that "want.exe" is in your path variable.
- In your "gmarathon" folder you will find the Want buildfile "want.xml", "dcc32.cfg" (where some compiler ("dcc32.exe") options are included which Want can't handle natively) and a file "release.ini" where the build number and the version string is managed.
- Make sure you have adjusted all paths in "want.xml". These are:
- The standard path to the directory where your Marathon library files reside.
- All library paths separated by components, if they differ from the defaults.
- Please compile "Touchbuild.dpr".
- The full path to your WinHelp compiler "HCW.exe".
- The full path to your InnoSetup command line compiler "ISCC.exe".
- Only for official snapshots: Make sure you have a working CVS setup, because a fresh checkout of the latest CVS content is required.
- Only for official snapshots: Adjust the paths in "Want.xml" to "CVS.exe" and "PSCP.exe" from your PuTTY distribution.
- Now you can use the batch file "build.bat" with various parameters to do e.g. a sourcecode snapshot. Here is a description of the targets:
- "help": Prints out a help screen.
- "compile": Compiles Marathon and all subprojects (Delphi and all components must be installed properly).
- "online_help": Compiles the online help using the Winhelp compiler.
- "source_snapshot": Adds all source files of Marathon and all subprojects to the file "./dist/Marathon_Source.zip".
- "binary_snapshot": Combines the targets "compile" and "online_help", afterwards it creates a setup file using InnoSetup and zips it to "./dist/Marathon_Binary.zip".
- "official_snapshots": Caution: Only use this target in conjunction with "build.bat", else the build will fail. First checks out the latest sourcecode from CVS into the folder "Official_Snapshots" (it is created by "build.bat"). Then it combines the targets "source_snapshot" and "binary_snapshot" to create the appropriate zip files. Finally the files are uploaded to SourceForge and the build number is increased and committed ("release.ini").
- "clean": Cleans up the "dist" directory.
Coding and CVS guidelines:
Here you will find binary and sourcecode snapshots which are done by "build.bat official_snapshots". This is the actual build number. To find out what has changed please have a look at the ChangeLog file or the raw commitlog file.
Here I have collected some guidelines which you should be aware of before you start to contribute:
Frequently Asked Questions:
- Use the same coding style as in the rest of the code (write reserved words in lower case, use the same indent and tab settings, etc.).
- Use comments to help others understand your code.
- Test your changes in all modules which are affected by your modifications.
- Make sure to ifdef your changes, if you are using Delphi 6 specific properties or methods. Generally you should avoid such incompatibilities whenever possible.
- Don't use additional 3rdParty or Delphi Enterprise specific components.
- Please update the ChangeLog file only with information which help us building an enduser readable project history.
- Commit your changes only with a comment (-m). This comment is automatically appended at the bottom of of each committed file. So please use meaningful comments and commit only files which are related to your change and the comment.
- Please just add files which you really have changed, e.g. don't commit .dfm's where you just have changed the left and top properties....
- When you add new files make sure you add binary files with the binary(-kb) tag.
- Question: What direction is the Marathon development moving?
- Answer: We are currently trying to get a first beta out of the door. There is a subproject at SourceForge which should help to understand what has been done and what is currently in development. If you want to contribute and have choosen a working area please let me know and I will setup an appropriate task for you.
- Question: Where does developer discussions take place?
- Answer: Please use always the developer forum at SourceForge. Of course you must be a logged in member to see and post to it.
Additional information and resources:
If you have any suggestions, bug reports or criticism please drop me an E-Mail.