Quick Start Guide

Get up and running with HarbourBuilder in five minutes. This guide walks you through creating your first application, from an empty project to a running native program.

1. Create Your First Project

Launch HarbourBuilder and select File → New Project. Choose a folder and project name. The IDE creates a main .prg file with a starter form definition:

#include "hbbuilder.ch"

function Main()

   local oForm

   DEFINE FORM oForm TITLE "My First App" ;
      SIZE 640, 480 FONT "Segoe UI", 10

   ACTIVATE FORM oForm CENTERED

return nil

This gives you an empty window, sized 640×480, centered on screen. The DEFINE FORM command is an xBase preprocessor macro that creates a native TForm object behind the scenes.

2. Add Controls

Open the Form Designer (double-click the form in the Project Manager) and use the Component Palette at the top of the IDE to drop controls onto the form:

1. Click the Standard tab in the palette.
2. Click the Button icon, then click on the form surface where you want it.
3. The Object Inspector on the left shows the button's properties — set cPrompt to "Say Hello".
4. Drag a Label from the palette and place it above the button.

Each control you drop generates the corresponding xBase code automatically:

local oForm, oBtn, oLabel

DEFINE FORM oForm TITLE "My First App" ;
   SIZE 640, 480 FONT "Segoe UI", 10

@ 30, 50 LABEL oLabel VALUE "Welcome to HarbourBuilder" ;
   OF oForm SIZE 250, 24

@ 70, 50 BUTTON oBtn PROMPT "Say Hello" ;
   OF oForm SIZE 120, 32

3. Handle Events

Select the button in the designer, switch to the Events tab in the Object Inspector, and double-click OnClick. The IDE jumps to the code editor with a method stub ready for you. You can also assign events directly in code:

oBtn:OnClick := { || MsgInfo( "Hello from HarbourBuilder!" ) }

For more complex logic, use a code block that calls a function:

oBtn:OnClick := { || OnBtnClick( oForm, oLabel ) }

static function OnBtnClick( oForm, oLabel )

   oLabel:SetValue( "Button clicked at " + Time() )
   oForm:SetTitle( "Clicked!" )

return nil

4. Build & Run

Press F9 (or select Run → Build & Run) to compile and launch your application. HarbourBuilder performs these steps automatically:

1. Preprocess — expands #xcommand macros (DEFINE FORM, BUTTON, etc.) into Harbour OOP calls.
2. Compile — the Harbour compiler produces C code, then the platform C/C++ compiler builds the native binary.
3. Link — links against the platform backend (Win32 API, Cocoa, or GTK3).
4. Execute — launches the resulting native executable.

Build output appears in the Messages panel at the bottom. Any errors are shown with clickable file/line references that jump directly to the source.

5. Save Your Project

Use File → Save Project (Ctrl+S) to save your work. HarbourBuilder stores project metadata in a .hbp file, which tracks:

• All source files (.prg) in the project.
• Form design data (control positions, properties, events).
• Build configuration (compiler flags, target platform, output path).
• Third-party library references.

The .hbp file is a plain-text format that works well with version control systems like Git.

Development Workflow

The typical HarbourBuilder development cycle follows four stages:

Press F9 at any time to go from design to a running application in seconds. Happy building!