This is by no means a fully comprehensive tutorial on how to use Delphi. It is basically the steps you need to follow, including screen dumps, to install the extra components which QuArK needs, setting a few options, and a couple of hints to make compiling easier. There are lots of tutorials for Delphi on the web (altho none spring to mind at the moment). The steps below will get you started using Delphi to help develop QuArK, after that it is up to you to experiment and explore the Delphi IDE and the QuArK source.

Remember, if you totally stuff things up you can always delete your QuArK source directory and do another checkout from source code repository without breaking anything.

The central core of QuArK is written in Delphi, with add-ons and lots of the map manipulation code written in Python.

Upto and including Delphi 5, you could only obtain commercial versions for which you had to pay a licence fee to Borland. Starting from Delphi 6, Borland have provided a Personal Edition of Delphi which is accompanied by a licence which says that you cannot use a Personal Edition of Delphi to produce commercial applications, and that you must make the source code of your applications available. For the purposes of developing QuArK this is ideal!

Delphi 6 or 7 Personal Edition can be downloaded from the Borland Delphi web site, or can sometimes be found on computer magazine cover CDs which seem to feature Delphi every six months or so (maybe ask a few friends if they have older magazines with cover CDs).

To download Delphi you need to have or to create a Borland account, this is a fairly painless procedure on the web. You also need to register your copy of Delphi after installing it - once again this is fairly painless and can be done automatically (if you have an active Internet connection) or on the web or via email (which takes a bit longer, but is still usually fairly quick).

Installing Delphi is a simple matter of running the executable which you downloaded or copied off a magazine cover CD. Or, if you have obtained a zipped version, unzip it first, and then run the setup program.

Installing the necessary components is covered in the Configuration section, below.

Delphi 6 Personal Edition takes a tad over 100MB to install, Delphi 7 Personal Edition is probably a bit larger. You should also allow at least 250MB for all the QuArK source (20MB if you are selective during check-out), which can be obtained from the SourceForge code repository.

If you are lucky enough to have access to a better copy of Delphi (e.g. one of the Professional or Enterprise editions), great! But you can fully compile QuArK with the Personal Editions.

Configuring Delphi falls into three main categories:

1. Setting general Delphi options,
2. Installing the required components,
3. And setting the QuArK project options.

(Note that the examples below are from Delphi 7, but the commands and dialogs are similar for earlier versions of Delphi. Delphi 6 should also still work, but for Delphi 5 some module name adjustments for StringUtils/SysUtils is required.)

Delphi options

There are a few Delphi options which I have found useful to set prior to doing anything. Select Tools - Environment Options from the Delphi main menu, then go to the Preferences tab (which is probably the first one displayed anyway). Ensure that the "Show compiler progress" and "Minimize on run" options are checked (the rest can be left as default). Next go to the Delphi Direct tab and unselect "Automatically poll network". This is a personal preference, and unless you want Delphi to poll the Borland web site every now and again to get news items and popup a window with them, it is a good idea to turn it off. Actually I've never read anything it does show, so maybe if you want to experiment then leave this option on. The next step complements the later step of installing the components. Even though you install the components, you still need to tell Delphi where to find the source files, and you do that in the Library tab. Click the ellipsis button next to the "Library path field". The Directories form will appear. In the list box are the current directories in the library path. To add a new directory (you will need to add one directory for each component which has been, or will be, installed as part of the extra components which QuArK uses. Click the ellipsis button on this form next to the edit field. Now browse to the source\components directory and click OK. Back on the Directories form notice that the directory you selected appears in the edit field, and the Add button is enabled. Click the Add button and the directory will be added to the end of the list. You will need to repeat the above two steps for each of the directories under the source\components directory EXCLUDING CVS (CVS is a special directory which WinCVS uses to track changes to the files). So you need to browse and add the directories: direct3d, jpeg, png and zip. After adding, your Directories window should look something like this. Now click OK to close the Directories window, then OK to close the Environment Options window.

Components

Delphi comes with a rich set of components, both visual components (those which correspond to actual things you can see on forms, such as buttons and edit fields) and non-visual components (such as timers, Internet protocol helpers and so on). The flexible QuArK interface makes use of some components which are not part of the standard Delphi component suite, they are supplied as part of the source (in the source\components directories). Installing them is a fairly painless procedure, as follows: Run Delphi, select File - Open from the main menu, change the file type to "Delphi packages (*.dpk)", browse to the source\components directory which you checked out of the CVS repository, select the file vclar40.dpk and click Open. A message might be displayed warning that the resources file was missing but was re-created. If so, just click OK. Also, if you are using Delphi 5 or later (the "40" in "vclar40.dpk" originates from Delphi 4) you might be advised that the package is in an older format, and would you like it to be converted. Again, if so, just Click Yes. A successful conversion (I am yet to see an unsuccessful one) would be indicated by the following dialog. Now the Package window should be visible.
In this window click the Install button icon at the top. Delphi will compile the package and register the components. Successful component registration will be indicated by something like the following message. To see where the new components are, scroll the component palette all the way to the right, and you should see tabs called Toolbar97, Exemples and Mars. Now select File - Close All from the Delphi main menu. You will be prompted to save changes to the project vclar40.dpk - you should NOT do this, so click No. The components have already been installed into the Delphi IDE, and if you do save the vclar40.dpk project then WinCVS will register that you have changed those files. So you do not need to save changes to the vclar40.dpk project.

QuArK project options

Before you can compile QuArK, you will almost certainly need to change some of the project options. Select File - Open, browse to the source directory, change the file type to "Delphi Project (*.dpr)" if necessary (most Delphi versions default to opening .dpr files, but Delphi 7 appears to remember the last file type you opened), select QuArK.dpr and click Open. Now a quick word about the directory structure. I have a directory called c:\src in which I keep all my source files (for all projects). There is a subdirectory c:\src\QuArK in which I checkout the QuArK source. So my working directory in WinCVS is c:\src\QuArK, and WinCVS creates a bunch of directories under that, like this: To keep the CVS source as clean as possible, I create two additional directories, one to hold a working copy of the runtime files (called "run") and one to hold temporary files, such as .dcu (Delphi compiled unit) files. I copy all of the contents of the "runtime" directory into the "run" directory EXCEPT the CVS subdirectories. CVS subdirectories tell WinCVS that the files in that directory should be checked for changes, and I do not want that to happen for the "run" and "tmp" directories, so I make sure there are no "CVS" directories under those two. WinCVS reports those directories and all their subdirectories as "NonCvs Folder" which is fine as I will never be committing anything in either of those two folders. If you have existing programming practices, then you should keep following it rather than introducing new practices just for QuArK. For example lots of people store all temporary files in one place, such as c:\temp (under older Windows) or %TEMP% (under Windows NT/2K/XP). In Delphi, with the QuArK project loaded, select Project - Options, and go to the Directories/Conditionals tab. Change the "Output directory" and the "Unit output directory" to be a working runtime directory (I would use c:\src\QuArK\run) and a temporary directory (I would use c:\src\QuArK\tmp) respectively. In conditional defines a little bit further down, if the word "Debug" appears, delete it. You only need this if you are doing extensive debugging of QuArK. Instead, using the drop down arrow to the right, select "PYTHON_BUNDLED". This is because the basic Python library is now included with the QuArK runtime files in the dll folder, eliminating the need of having to install Python or the old Mini-python package that was required with older versions of QuArK. Now go to the Linker tab and unselect the "Include TD32 debug info" - once again this is not necessary if you are not doing extensive debugging of QuArK, and will drastically increase the size of the QuArK.exe which Delphi compiles if it is selected. If you are using Delphi 7, there are a bunch of extra warnings which Delphi 7 produces. Most of these you do not have to see, and the compile slows to an absolute crawl if they are left on. I tried to compile with all warnings enabled, and Delphi produced over 4500 warnings, compiling about 10 lines a second, so I killed the compile, disabled the warnings, and now a full rebuild of QuArK takes about 12 seconds. Still in the Options window, go to the Warnings tab, and unselect the following warnings:

• Comparing signed and unsigned types - widened both operands
• Combining signed and unsigned types - widened both operands
• Suspicious typecast
• Unsafe type
• Unsafe code
• Unsafe typecast

Note that they do not all fit into one screen in the picture below, you will need to scroll to find all the options. Finally click OK to save the project options, and select File - Save All to save the new project options. Note that these settings are saved in the QuArK.dof and QuArK.cfg files, and WinCVS will indicate that those files have been modified. You should NOT commit those changes (unless you have changed something else fundamental in the project options) as these changes will affect all developers, and options saved in a later version of Delphi might not work in an earlier version.

Here are a few notes about using Delphi.

Delphi file types

A project consists of a .dpr file (Delphi project), a number of .pas files (Object Pascal source files) and .dfm files (Delphi forms). There are a few other files containing resources (.res files), project configuration (.dof and .cfg), include files (.inc), and possibly assembler files (.asm). When Delphi compiles a .pas file, it creates a corresponding .dcu file (Delphi compiled unit). Also every .dfm file will have a corresponding .pas file (but not necessarily the other way around).

Compiling with Delphi

.dcu files are temporary and can be deleted at any time. However, if you delete a .dcu file then Delphi has to compile the corresponding .pas file again, whether it has changed since the last compile or not. If you do a compile in Delphi (by selecting Project - Compile from the menu or by pressing Ctrl-F9) Delphi checks all the .pas files and all the .dcu files, and only compiles those .pas files which have been changed since the corresponding .dcu file was last compiled. This is also true for .pas files which have been changed inside the Delphi IDE but not yet saved - they are considered as changed by the compiler. Also, Delphi will recompile .pas files which rely on other .pas files e.g. if file1.pas uses file2.pas, and file2.pas has been changed, then both file1.pas and file2.pas will be recompiled. Alternatively you can force a full recompile of everything by selecting Project - Build from the menu. Another compile-type option which takes a lot less time to process is to "syntax check" the source without actually compiling anything. This acts like a Ctrl-F9 by parsing all source files which have been changed since the last proper compile, but does not generate any new .dcu files, nor does it generate a .exe file. This can be used if you very quickly want to check whether they syntax of something you changed is correct. A full rebuild of QuArK on my PC takes around 12 seconds, a syntax check takes about 2 seconds, most of which is Delphi checking file modification times to see how much it has to check.

Configuring the IDE

Select Tools - Editor Options from the menu, and the editor options dialog will appear. There are a number of options you can set here to customise the appearance and operation of the editor, including changing the font use to display text, and also the colours used for syntax hiliting. Experiment with the options to find a setting that you like - it does make a huge difference in programming if you are reading code with nice colours and a nice font and with key strokes that you are familiar with rather than struggling to read poorly coloured text using unfamiliar keystrokes. A few minutes investigating the editor configuration could save you lots of frustration later on.

Common keystrokes

Here are a few common keystrokes I have found useful. Note that these assume that the standard Delphi key mappings are selected.

• Ctrl-F9 - compiles only those units (.pas files) which have been changed, produces a new QuArK.exe
• F9 - build and run - does a compile (like Ctrl-F9) and then runs QuArK
• F11 - toggles between the Object Inspector (where you can set component properties such as label captions, button names, panel colours etc.) and the form or code view
• F12 - toggles between showing the form and the Object Pascal code (toggles the .dfm and .pas views, if there is a .dfm associated with the .pas)
• Ctrl-F - find
• F3 - find next
• F5 - sets a breakpoint (indicated by a red dot and, by default, a red line hiliting a line of code). Note: if the internal debugger stops at a break point you can press F9 to start running again, which will keep running until it hits the next breakpoint
• F7 - step into - runs a single line of Delphi code in the integrated debugger, if the line of code calls a procedure/function then run the first line of code inside that proc/func
• F8 - step over - runs a single line of Delphi code in the integrated debugger, if the line of code calls a procedure/functoin then run the entire proc/func as if it were a single line of code (i.e. does not single-step thru each line in the proc/func)
• Ctrl-LMB - if you hold down the Ctrl key and move the mouse over the Delphi source code, each identifier will be underlined. If you click the left mouse button (LMB) Delphi will do it's best to open the source file where the identifier is declared and position the cursor on the declaration