Build & Run
Press F9 to compile, link, and run your application in a single step. HarbourBuilder orchestrates the entire build process automatically, from preprocessing your .prg files to launching the resulting executable.
Press F9 and HarbourBuilder handles everything: Harbour compilation, C compiler invocation, linking, resource embedding, and launching your app. No makefiles, no command-line scripts, no manual steps.
The 7-Step Build Process
Step Details
| Step | Tool | Input | Output | Description |
|---|---|---|---|---|
| 1. Preprocess | Harbour | .prg, .ch | .ppo | Processes #include, #define, and xBase preprocessor directives. |
| 2. Compile | Harbour | .ppo | .c | Translates preprocessed Harbour source into C code. |
| 3. Compile C | C Compiler | .c | .o / .obj | Invokes MSVC, BCC, GCC, or Clang to produce object files. |
| 4. Link | Linker | .o / .obj | .exe | Links object files with Harbour runtime libraries and system libs. |
| 5. Embed | Resource tool | icons, images | .exe | Embeds application resources (icons, images, forms) into the executable. |
| 6. Validate | IDE | build log | report | Checks for compilation/linking errors and displays them in the Build Messages panel. |
| 7. Launch | IDE | .exe | running app | Launches the compiled application for testing. |
Progress Dialog
During the build, a progress dialog shows real-time status of each step:
- Progress bar — visual indication of build completion across all 7 steps.
- Current step label — shows which step is executing (e.g., "Compiling main.prg...").
- Cancel button — abort the build at any point.
- Log output — raw compiler and linker output shown in a scrollable text area.
Error Dialog
If the build fails, an error dialog appears with:
- Error count — total number of errors encountered.
- Warning count — total number of non-fatal warnings.
- Clickable error list — each error shows the file, line number, and description.
- Double-click to navigate — clicking an error opens the source file at the exact line.
Build Messages Panel
The Build Messages panel at the bottom of the IDE shows the output from every build:
| Column | Description |
|---|---|
| Type | Error (red), Warning (yellow), or Info (blue) icon. |
| File | Source file where the message originated. |
| Line | Line number of the issue. |
| Message | Compiler or linker error description. |
Double-click any error in the Build Messages panel to jump directly to that line in the source editor. The editor highlights the problematic line for quick identification.
Recent Build Improvements
The build system has been enhanced with several important improvements:
Code Cleanup Before Assembly
- Separator stripping: "----" separators are automatically removed from form files before assembly to prevent Harbour "Incomplete statement" parse errors.
- Duplicate header removal: Duplicate
#include "hbbuilder.ch"and#include "classes.prg"statements are stripped to prevent duplicate class definitions and linker errors. - Debug build support: The same cleanup is applied to debug builds (
TBDebugRun) to ensure consistent behavior.
Improved Project Loading
- Deferred control creation: The
UI_FormCreateChildren()function creates Win32 handles for deferred controls afterRestoreFormFromCode. - Better form initialization: Forms are shown before restoring controls to ensure proper parent HWNDs exist for band creation.
Enhanced Code Generation
- Smart launcher placement: The
FUNCTION FormN()launcher is placed at the end of generated files, after user methods, to prevent accumulation of duplicate function definitions. - Method preservation: User method implementations are properly preserved during code regeneration cycles.
Keyboard Shortcuts
| Shortcut | Action |
|---|---|
| F9 | Compile and run |
| Ctrl+F9 | Compile only (do not run) |
| Shift+F9 | Rebuild all (clean + full compile) |
| F5 | Start debugging (compile with debug flags) |
| Ctrl+Shift+B | Build current file only |
Multi-Compiler Support
HarbourBuilder supports multiple C compilers for the linking step. Choose the one that best suits your platform and licensing:
| Compiler | Platforms | License | Notes |
|---|---|---|---|
| MSVC (Microsoft Visual C++) | Windows | Proprietary (free Build Tools available) | Recommended for Windows. Best performance and compatibility. |
| BCC (Borland C++ Compiler) | Windows | Proprietary (free version available) | Legacy support. Compatible with older Harbour builds. |
| GCC | Linux, macOS (via Xcode) | GPL | Default on Linux. Available on macOS via Homebrew or Xcode. |
| Clang | macOS, Linux | BSD-style | Recommended for macOS. Part of Xcode Command Line Tools. |
Smart Rebuild
HarbourBuilder uses a dependency-tracking system to avoid unnecessary recompilation:
- File modification timestamps — only .prg files modified since the last build are recompiled.
- Include dependency tracking — if a .ch header file changes, all .prg files that #include it are recompiled.
- Object file validation — .o / .obj files are reused if their source has not changed.
- Incremental linking — the linker only re-links changed object files when possible.
Press F9 for a smart build (only changed files). Press Shift+F9 for a full rebuild (clean everything and recompile all files). Use a full rebuild after changing compiler settings, adding library dependencies, or when incremental builds produce unexpected results.
Project Options
Configure your build settings via Project > Options:
| Category | Options |
|---|---|
| Compiler | Harbour flags: -n2, -w3, -gc, -gl, -gh, -b, and custom flags. |
| C Compiler | Select compiler (MSVC/BCC/GCC/Clang), include paths, defines, optimization level. |
| Linker | Library paths, additional libraries, subsystem (console/GUI), output file name. |
| Resources | Icon file, manifest, embedded files, resource compiler flags. |
| Output | Output directory, executable name, working directory, command-line arguments. |
| Debug | Enable debug build (-gh -b), generate map file, symbol output. |
Build Output Directory
By default, compiled output goes to the output/ folder within your project.
You can customize this in Project Options:
| File | Description |
|---|---|
myapp.exe | The compiled application (Windows) or binary (macOS/Linux). |
myapp.hrb | Bytecode file (when compiled with -b flag for debugging). |
myapp.map | Linker map file (if enabled in project options). |
*.o / *.obj | Intermediate object files (retained for smart rebuild). |
For distribution, do a clean rebuild (Shift+F9) without debug flags (-gh -b). This produces a smaller, faster executable with no debug symbols embedded.