Harbour Make (hbmk2)

Harbour Make (hbmk2) 3.2.0dev (r2013-04-03 03:33)
Copyright (c) 1999-2013, Viktor Szakáts


hbmk2 [options] [<script[s]>] <src[s] [.prg|.c|.obj|.o|.rc|.res|.def|.po|.pot|.hbl|@.clp|.d|.ch]>


hbmk2 is an integrated and portable build tool, making it possible to create various types of executable binaries (executable, dynamic library, static library, Harbour portable binary) out of multiple types of source files (C, C++, Objective-C, Harbour, gettext translations, Windows resources). ‘Integrated’ means that a single hbmk2 project file can control all or most aspects of the build process. ‘Portable’ means that a single hbmk2 project file can control the build on all supported OS platforms and across all supported C compilers. It also aims to cover the majority of build tasks via short and simple project files (options). hbmk2 supports pure -non-Harbour- C/C++/Objective-C projects as well. In order to achieve above goals, hbmk2 will autodetect Harbour, C compiler and other required tools, then configure and call them appropriately. hbmk2 allows to extend the types of supported source files via plugins.

Besides building executables, hbmk2 is able to run Harbour scripts (both source and precompiled) directly, and it also features an interactive shell prompt.


  • -o<outname> output file name
  • -l<libname> link with <libname> library. <libname> should be without path, extension and ‘lib’ prefix (unless part of the name). Do not add core Harbour libraries, they are automatically added as needed. If <libname> starts with a ‘-‘ character, the library will be removed from the list of libraries at link time.
  • -L<libpath> additional path to search for libraries
  • -i<p>|-incpath=<p> additional path to search for headers
  • -static|-shared link with static/shared libs
  • -gt<name> link with GT<name> GT driver, can be repeated to link with more GTs. First one will be the default at run-time
  • -inc[-] enable/disable incremental build mode (default: disabled)
  • -hbexe create executable (default)
  • -hblib create static library
  • -hbdyn create dynamic library (without linked Harbour VM)
  • -hbdynvm create dynamic library (with linked Harbour VM)
  • -mt|-st link with multi/single-thread Harbour VM
  • -gui|-std create GUI/console executable
  • -main=<mainfunc> override the name of starting function/procedure
  • -request=<func> force function/procedure to be linked
  • -fullstatic link with all static libs
  • -pic[-] create position independent object code (always enabled in -hbdyn/-hbdynvm modes)
  • -[full|fix]shared create shared Harbour binaries without/with absolute dir reference to Harbour library (default: ‘fullshared’ when Harbour is installed on system location, ‘fixshared’ otherwise) (fix/full option in *nix only)
  • -nulrdd[-] link with nulrdd
  • -debug[-] add/exclude C compiler debug info. For Harbour level debug, use Harbour option -b as usual
  • -optim[-] toggle C compiler optimizations (default: on)
  • -cpp[-] force C++/C mode
  • -cpp=<value> select C++ mode. Allowed values are: def, yes, no
  • -map[-] create (or not) a map file
  • -implib[-] create (or not) an import library (in -hbdyn/-hbexe mode). The name will have a postfix added.
  • -implib=<output> create import library (in -hbdyn/-hbexe mode) name to <output> (default: same as output)
  • -ln=<link> create symbolic link pointing to <output> (<link> is considered relative to <output>)
  • -strip[-] strip (no strip) binaries
  • -trace[-] show commands executed
  • -beep[-] enable (or disable) single beep on successful exit, double beep on failure
  • -ignore[-] ignore errors when running compiler tools (default: off)
  • -hbcppmm[-] override standard C++ memory management functions with Harbour ones
  • -winuni[-] select between UNICODE (WIDE) and ANSI compilation modes (default: ANSI) (Windows only. For WinCE it is always set to UNICODE)
  • -nohblib[-] do not use static core Harbour libraries when linking
  • -nodefgt[-] do not link default GTs (effective in -static mode)
  • -nolibgrouping[-] disable library grouping on gcc based compilers
  • -nomiscsyslib[-] do not add extra list of system libraries to default library list
  • -traceonly show commands to be executed, but do not execute them
  • -warn=<level> set C compiler warning level
    <level> can be: max, yes, low, no, def (default: yes)
  • -safe[-] enable safety options in C compiler/linker (default: enabled on Windows, disabled on other systems)
  • -compr=<level> compress executable/dynamic lib (needs UPX tool)
    <level> can be: yes, no, min, max
  • -run[-] run/do not run output executable
  • -vcshead=<file> generate .ch header file with local repository information. Git, SVN, Mercurial, Bazaar, Fossil, CVS and Monotone are currently supported. Generated header will define preprocessor constant _HBMK_VCS_TYPE_ with the name of detected VCS and _HBMK_VCS_ID_ with the unique ID of local repository. If no VCS system is detected, a sequential number will be rolled automatically on each build.
  • -tshead=<file> generate .ch header file with timestamp information. Generated header will define preprocessor constants _HBMK_BUILD_DATE_, _HBMK_BUILD_TIME_, _HBMK_BUILD_TIMESTAMP_ with the date/time of build
  • -icon=<file> set <file> as application icon. <file> should be a supported format on the target platform (not supported by some platforms/compilers). On Windows, it is implemented by generating and linking a resource file.
  • -manifest=<file> embed manifest <file> in executable/dynamic lib (Windows only)
  • -sign=<key> sign executable with <key> (Windows and Darwin only). On Windows signtool.exe is used (part of MS Windows SDK) or posign.exe (part of Pelles C 7), in that order, both autodetected.
  • -signpw=<pw> use <pw> as password when signing executable (Windows and Darwin only)
  • -instfile=<g:file> add <file> in to the list of files to be copied to path specified by -instpath option. <g> is an optional copy group (case sensitive), it must be at least two characters long. In case you do not specify <file>, the list of files in that group will be emptied.
  • -instpath=<g:path> copy target file(s) to <path>. if <path> is a directory, it should end with path separator, in this case files specified by -instfile option will also be copied. can be specified multiple times. <g> is an optional copy group, it must be at least two characters long. Build target will be automatically copied to default (empty) copy group. There exist following built-in <g> groups: ‘depimplib’ for import libraries and ‘depimplibsrc’ for import library source (.dll) files, both belonging to dependencies.
  • -instforce[-] copy target file(s) to install path even if already up to date
  • -depimplib[-] enable (or disable) import library generation for import library sources specified in -depimplibs= options (default: yes)
  • -stop[=<text>] stop without doing anything and display <text> if specified
  • -echo=<text> echo text on screen
  • -pause force waiting for a key on exit in case of failure (with alternate GTs only)
  • -exitstr show error result as human readable text on exit
  • -info turn on informational messages
  • -quiet[-] suppress all screen messages
  • -bldf[-] inherit all/no (default) flags from Harbour build
  • -bldf=[p][c][l] inherit .prg/.c/linker flags (or none) from Harbour build
  • -F<framework> link with <framework> framework (Darwin only)
  • -prgflag=<f> pass single flag to Harbour compiler
  • -cflag=<f> pass single flag to C compiler
  • -resflag=<f> pass single flag to resource compiler (Windows only)
  • -ldflag=<f> pass single flag to linker (executable)
  • -dflag=<f> pass single flag to linker (dynamic library)
  • -aflag=<f> pass single flag to linker (static library)
  • -iflag=<f> pass single flag to import library creation command
  • -signflag=<f> pass single flag to code sign command
  • -runflag=<f> pass single flag to output executable when -run option is used
  • -cflag+=<f> pass single flag to C compiler overriding C compiler flags added by hbmk2 itself. Use with caution.
  • -ldflag+=<f> pass single raw option to linker (executable) after the library list. Use with caution.
  • -dflag+=<f> pass single raw option to linker (dynamic library) after the library list. Use with caution.
  • -3rd=<f> options/flags reserved for 3rd party tools, always ignored by hbmk2 itself
  • -env:<e>[<o>[<v>]] alter local environment. <e> is the name of the environment variable to alter. <o> can be ‘=’ to set/override, ‘-‘ to delete, ‘+’ to append to the end of existing value, ‘#’ to insert to the beginning of existing value. <v> is the value to set/append/insert.
  • -jobs=<n> start n compilation threads (multiprocess platforms only)
  • -head=<m> control source header parsing (in incremental build mode)
    <m> can be: native (uses compiler to extract dependencies), full (default, uses simple text parser on the whole file), dep, off
  • -rebuild rebuild (in incremental build mode)
  • -rebuildall rebuild with sub-projects (in incremental build mode)
  • -clean clean (in incremental build mode)
  • -workdir=<dir> working directory
    (default: .hbmk/<platform>/<compiler> [*] in incremental mode, OS temp directory otherwise)
  • -hbcontainer virtual build target, it does not create anything. Useful for creating an .hbp with the sole purpose of referencing sub-projects
  • -hbimplib create import library (Windows only)
  • -hbl[=<output>] output .hbl filename. %{hb_lng} macro is accepted in filename
  • -lng=<languages> list of languages to be replaced in %{hb_lng} macros in .pot/.po filenames and output .hbl/.po filenames. Comma separated list:
  • -po=<output> create/update .po file from source. Merge it with previous .po file of the same name
  • -minipo[-] do (not) add Harbour version number and source file reference to .po (default: add them)
  • -rebuildpo recreate .po file, thus removing all obsolete entries in it
  • -hbx=[<.ch>] Create Harbour header (in .hbx format) with all external symbols. Empty parameter will disable it.
  • -autohbc=<.ch:.hbc> <.ch> is a header file name. <.hbc> is a .hbc filename to be automatically included in case the header is found in any of the compiled sources. (EXPERIMENTAL)
  • -deppkgname=<d:n> <d> is the name of the dependency. <n> name of the package dependency. Can be specified multiple times.
  • -depkeyhead=<d:h> <d> is the name of the dependency. <h> is the key header (.h) of the package dependency. Multiple alternative headers can be specified.
  • -depoptional=<d:f> <d> is the name of the dependency. <f> can be ‘yes’ or ‘no’, specifies whether the dependency is optional. Default: no
  • -depcontrol=<d:v> <d> is the name of the dependency. <v> is a value that controls how detection is done. Accepted values: no, yes, force, nolocal, local. Default: content of environment variable HBMK_WITH_<d>
  • -depincroot=<d:r> <d> is the name of the dependency. Set <r> as root directory for paths specified in -depincpath options.
  • -depincpath=<d:i> <d> is the name of the dependency. Add <i> to the header detection path list.
  • -depincpathlocal=<d:i> <d> is the name of the dependency. Add <i> to the header detection path list, where <i> is pointing to a directory local to the project and containing an embedded (aka. ‘locally hosted’) dependency.
  • -depimplibs=<d:dll> <d> is the name of the dependency. Add <dll> to the import library source list.
  • -depimplibd=<d:lib> <d> is the name of the dependency. Set generated import library name to <lib>
  • -depfinish=<d> <d> is the name of the dependency. Closes the dependency definition and does the actual dependency detection, setting all predefined filter macro variables and build options accordingly. Optional, if omitted, detection will take place after processing all options.
  • -plugin=<filename> add plugin. <filename> can be: .hb, .prg, .hrb
  • -pi=<filename> pass input file to plugins
  • -pflag=<f> pass single flag to plugins

Options below are available on command-line:

  • -target=<script> specify a new build target. <script> can be .prg (or no extension) or .hbp file. Note that .hbp files are automatically considered as separate build targets.
  • -hbrun run build target
  • -hbraw stop after running Harbour compiler
  • -hbcmp|-clipper stop after creating the object files
    create link/copy hbmk2 to hbcmp/clipper for the same effect
  • -hbcc accept raw C flags
    create link/copy hbmk2 to hbcc for the same effect
  • -hblnk accept raw linker flags
  • -autohbm[-] enable (or disable) processing of hbmk.hbm in current directory (default: yes)
  • -hb10 enable Harbour 1.0.x compatibility mode
  • -hb20 enable Harbour 2.0.x compatibility mode
  • -hb30 enable Harbour 3.0.x compatibility mode
  • -xhb enable xhb mode
  • -hbc enable pure C mode
  • -rtlink
  • -blinker
  • -exospace emulate Clipper compatible linker behavior
    create link/copy hbmk2 to rtlink/blinker/exospace for the same effect
  • -hbreg[=global] register Harbour Script (.hb) with hbmk2 (Windows only)
  • -hbunreg[=global] unregister Harbour Script (.hb) from hbmk2 (Windows only)
  • -find <text> lists all known Harbour functions that contain <text> in their name, along with their package (case insensitive, accepts multiple values, can contain wildcard characters)
  • -hbmake=<file> convert hbmake project <file> to .hbp file
  • -xbp=<file> convert .xbp (xbuild) project <file> to .hbp file
  • -xhp=<file> convert .xhp (xMate) project <file> to .hbp file
  • –hbdirbin output Harbour binary directory to stdout
  • –hbdirdyn output Harbour dynamic library directory to stdout
  • –hbdirlib output Harbour static library directory to stdout
  • –hbdirinc output Harbour header directory to stdout
  • –hbinfo[=nested] output Harbour build information to stdout. Output is in JSON format. The included paths always contain forward slashes. Each JSON block is followed by an 0x0A byte.
  • -plat=<platform> override default target platform (default: automatic)
  • -cpu=<cpu> override default target CPU (default: automatic) (EXPERIMENTAL)
  • -comp=<compiler> override C compiler autodetection
    Special value:
    – bld: use original build settings (default on *nix)
  • -build=<name> specify a build name
  • -lang=<lang> override default language. <lang> is an ISO language code.
  • -width=<n> set output width to <n> characters (0=unlimited).
  • -shl show sub-project level in output lines
  • -viewhelp long help in text viewer
  • -longhelp long help
  • -longhelpmd long help in Markdown format
  • -harbourhelp Harbour compiler help (all Harbour compiler options are accepted as is by hbmk2)
  • -credits Harbour compiler credits
  • -build Harbour compiler build information
  • -version display version header only

Options below are internal/developer ones (compatibility not guaranteed):

  • -debugtime measure time spent on the build
  • -debuginc display internals of incremental build
  • -debugstub display content of all internally generated source files
  • -debugi18n display internals on translation file generation
  • -debugdepd display internals of dependency detection
  • -debugpars display all input parameters in processing order
  • -debugrte generate a run-time error

You can sym-link/copy/rename hbmk2 to the following names to alter default mode of operation:

  • hbrun*|*hbrun mode script runner / interactive shell
  • hbrund|hbrun*d mode script runner / interactive shell in debug mode
  • harbour mode -hbraw (emulate – raw – Harbour compiler)
  • clipper mode -hbcmp (emulate Clipper compiler)
  • rtlink mode -rtlink (emulate Clipper linker)
  • exospace mode -rtlink (emulate Clipper linker)
  • blinker mode -rtlink (emulate Clipper linker)
  • *10 option -hb10
  • *20 option -hb20
  • *30 option -hb30
  • x\* option -xhb
  • hbcmp*|*hbcmp mode -hbcmp (emulate Harbour compiler producing a binary object)
  • hbcc*|*hbcc mode -hbcc (emulate C compiler)
  • hblnk*|*hblnk mode -hblnk (emulate C linker)
  • hbexe*|*hbexe mode -hbexe
  • hblib*|*hblib mode -hblib
  • hbdyn*|*hbdyn mode -hbdyn


  • *.hbp project file. Can contain any number of command-line options, which are expected to create an output. Lines beginning with ‘#’ character are ignored, otherwise newline is optional and options are space separated, just like on the command-line. You must enclose option containing space in double quotes. Each .hbp file reference will be executed as a sub-project.
  • *.hbm collection of options. Can be used to collect common ones into a file and include that into project files. Uses same format as .hbp files.
  • *.hbc collection of options that accompany components (aka ‘libs’, aka packages). Use different syntax than command-line and .hbp/.hbm files. Lines beginning with ‘#’ character are ignored, each directive must be placed in separate line.
  • *.ch if passed directly as a source file, it will be used as additional standard header
  • hbmk.hbc standard .hbc file that gets automatically processed, if present. Possible location(s) (in order of precedence) [*]: %APPDATA%\.harbour, <hbmk2 directory>
  • hbmk.hbm optional .hbm file residing in current working directory, which gets automatically processed before other options
  • $hb_pkg_dynlib.hbm special .hbm file embedded inside hbmk2. It manages the details of creating a dynamic library (in the style of Harbour contribs).
  • $hb_pkg_install.hbm special .hbm file embedded inside hbmk2. It manages the details of installing build targets and related package files to standard locations (in the style of Harbour contribs).
  • *.hb Harbour script
  • *.hrb Harbour portable binary (aka precompiled Harbour script)
  • hbstart.hb startup Harbour script for interactive Harbour shell. It gets executed automatically on shell startup, if present. Possible locations (in order of precedence) [*]: .\, %APPDATA%\.harbour, <hbmk2 directory>
  • shell plugins .hb and .hrb plugins for interactive Harbour shell. They may reside in [*]: %APPDATA%\.harbour\
  • .hb_history stores command history for interactive Harbour shell. You can disable history by making the first line ‘no’ (without quotes and with newline). Resides in [*]: %APPDATA%\.harbour\
  • hb_extension list of extensions to load in interactive Harbour shell. One extension per line, part of line beyond a ‘#’ character is ignored. Alternate filename on MS-DOS: hb_ext.ini. Resides in [*]: %APPDATA%\.harbour\

Macro variables:

  • ${hb_root} directory of hbmk2
  • ${hb_dir} directory of the filename it is used in
  • ${hb_dirname} top directory of the filename it is used in
  • ${hb_name} name of the filename it is used in (without directory and extension)
  • ${hb_self} full filename it is used in
  • ${hb_curdir} current working directory
  • ${hb_tempdir} OS directory for temporary files
  • ${hb_targetname} name of the project (without directory and extension). Returns .adhoc. if there is not project file.
  • ${hb_targettype} type of the project (hbexe, hblib, hbdyn, hbdynvm, hbimplib, hbppo, hbhrb, hbcontainer)
  • ${hb_plat} selected platform
  • ${hb_comp} selected C compiler
  • ${hb_comp_ver} C compiler version
  • ${hb_build} build name
  • ${hb_cpu} selected CPU
  • ${hb_work} default base workdir name
  • ${hb_workdynsub} default workdir subdirectory for dynamic library targets
  • ${hb_dynprefix} dynamic library prefix
  • ${hb_dynsuffix} dynamic library suffix
  • ${hb_dynext} dynamic library extension
  • ${hb_ver} Harbour version in hexadecimal triple byte format. F.e.: 030200
  • ${hb_verstr} Harbour version in human readable format <major>.<minor>.<release><status>. F.e.: 3.2.0dev
  • ${hb_major} Harbour major version number
  • ${hb_minor} Harbour minor version number
  • ${hb_release} Harbour release version number
  • ${hb_status} Harbour version status
  • ${hb_revision} Harbour revision
  • ${hb_host_plat} Harbour host platform
  • ${hb_host_plat_unix} returns ‘1’ if Harbour host platform is *nix compatible
  • ${hb_bin} Harbour binary directory
  • ${hb_lib} Harbour static library directory
  • ${hb_lib3rd} Harbour 3rd party static library directory
  • ${hb_dyn} Harbour dynamic library directory
  • ${hb_inc} Harbour header directory
  • ${hb_addons} Harbour add-ons base directory
  • ${hb_first} name of source file that holds the entry function (without directory and extension)
  • ${hb_outputdir} directory of the output
  • ${hb_outputname} name of the output (without extension)
  • ${hb_level} sub-project recursion level
  • ${<depname>} returns the header directory of dependency <depname>, or ‘1’ if it is not detected
  • ${<envvar>} returns the value of the environment variable <envvar>

Filters (you can combine and/or negate them):

  • {<platform>} target platform. Where <platform> can be any value accepted by -plat= option.
  • {<compiler>} target C compiler. Where <compiler> can be any value accepted by -comp= option.
  • {<cpu>} target CPU. Where <cpu> can be any of: x86, x86_64, ia64, arm, mips, sh
  • {<targettype>} build target type. Where <targettype> is any of the values returned by macro variable ${hb_targettype}.
  • {mt} build target is multi-threaded (see -mt option)
  • {st} build target is single-threaded (see -st option)
  • {gui} GUI target (see -gui option)
  • {std} console target (see -console option)
  • {debug} C level debugging is enabled (see -debug option)
  • {nodebug} C level debugging is disabled (see -debug- option)
  • {shared} shared build (see -shared and related options)
  • {static} static build (see -static and related options)
  • {lngcpp} forced C++ mode (see -cpp option)
  • {lngc} forced C mode (see -cpp- option)
  • {winuni} Windows UNICODE (WIDE) mode (see -winuni option)
  • {winansi} Windows ANSI mode (see -winuni- option)
  • {unix} target platform is *nix compatible (bsd, hpux, sunos, beos, qnx, android, vxworks, symbian, linux, darwin, cygwin, minix, aix)
  • {allwin} target platform is Windows compatible (win, wce)
  • {allgcc} target C compiler belongs to gcc family (gcc, mingw, mingw64, mingwarm, djgpp, gccomf, clang, open64, pcc)
  • {allmingw} target C compiler is mingw* (mingw, mingw64, mingwarm)
  • {allmsvc} target C compiler is msvc* (msvc, msvc64, msvcia64, msvcarm)
  • {allbcc} target C compiler is bcc* (bcc, bcc64)
  • {allpocc} target C compiler is pocc* (pocc, pocc64, poccarm)
  • {allicc} target C compiler is icc* (icc, iccia64)
  • {hb10} Harbour 1.0.x compatibility mode (see -hb10 option)
  • {hb20} Harbour 2.0.x compatibility mode (see -hb20 option)
  • {hb30} Harbour 3.0.x compatibility mode (see -hb30 option)
  • {xhb} xhb mode (see -xhb option)
  • {hb_ispath='<file|dir>’} filter will pass if <file> or <dir> name exists on disk.
  • {MACRO} filter will pass if ${MACRO} value is not empty and not equal to ‘0’ or ‘no’ (case insensitive)
  • {MACRO='<value>’} filter will pass if ${MACRO} value equals to <value> (case insensitive).
  • {MACRO>'<value>’} filter will pass if ${MACRO} value is larger than <value> (case insensitive).
  • {MACRO<‘<value>’} filter will pass if ${MACRO} value is smaller than <value> (case insensitive).

Predefined constants in sources:

  • __HBSCRIPT__HBMK_PLUGIN when an .hb script is compiled as hbmk2 plugin
  • __HBEXTREQ__ when an .hbx source file is present in a project (available in Harbour sources)
  • HBMK_HAS_<hbcname> when <hbcname>.hbc package is linked to the build target. The value is the version= value from the .hbc file, converted to a decimal number, which is ‘1’, if not specified. (available in Harbour sources)
  • HBMK_HAS_<depname> when <depname> dependency was detected (available in C sources)
  • __HBSCRIPT__HBSHELL when a Harbour source file is run as a shell script
  • <standard Harbour> __PLATFORM__*, __ARCH*BIT__, __*_ENDIAN__, etc…

Predefined constants in build files (they are available after ‘-depfinish=<depname>’ / ‘depfinish=<depname>’):

  • HBMK_HAS_<depname> when <depname> dependency was detected
  • HBMK_DIR_<depname> return the header directory where <depname> was detected, or empty if it was not.
  • HBMK_HAS_<depname>_LOCAL when <depname> dependency was detected in a location configured by -depincpathlocal= option

Environment variables:

  • HBMK_OPTIONS accepts any options as if they were passed in the beginning of the command-line
  • HB_PLATFORM accepts same values as -plat= option
  • HB_COMPILER accepts same values as -comp= option
  • HB_CPU accepts same values as -cpu= option
  • HB_BUILD_NAME accepts same values as -build= option
  • HB_LANG accepts same values as -lang= option
  • HB_USER_LIBS accepts same values (space separated) as -l option
  • HB_USER_LIBPATHS accepts same values (space separated) as -L option
  • HB_USER_PRGFLAGS options to be passed to Harbour compiler (before command-line options)
  • HB_USER_CFLAGS options to be passed to C compiler (before command-line options)
  • HB_USER_RESFLAGS options to be passed to resource compiler (before command-line options) (Windows only)
  • HB_USER_LDFLAGS options to be passed to linker (executable) (before command-line options)
  • HB_USER_DFLAGS options to be passed to linker (dynamic library) (before command-line options)
  • HB_USER_AFLAGS options to be passed to linker (static library) (before command-line options)
  • HB_COMPILER_VER override C compiler version autodetection (gcc and msvc compiler families only). Format: <15><00>[.<00>] = <major><minor>[.<revision>]
  • HB_CCPATH override C compiler executable directory (gcc compiler families only)
  • HB_CCPREFIX override C compiler executable prefix (gcc compiler families only)
  • HB_CCSUFFIX override C compiler executable suffix (gcc compiler families only)
  • HB_INSTALL_PREFIX override Harbour base installation directory
  • HB_INSTALL_ADDONS override Harbour base add-ons directory
  • HB_EXTENSION space separated list of extensions to load in interactive Harbour shell

.hbc directives (they should be written in separate lines):

  • echo=<msg> display <msg>
  • skip=[<msg>] skip processing the rest of the .hbc file. Display <msg>, if specified.
  • stop=[<msg>] stop the build. Display <msg>, if specified.
  • sources= add space separated list of files as input files
  • headers= add space separated list of .ch format headers as standard header
  • libs= add space separated list of libraries (see more at -l option)
  • frameworks= add space separated list of frameworks (Darwin only)
  • requests= add space separated list of symbols to force link to the build target
  • syslibs= add space separated list of libraries as system libraries (before regular libraries)
  • hbcs= embed space separated list of .hbc files. Names without the extension is accepted. These references are processed in place.
  • autohbcs= space separated list of values as in -autohbc= option
  • libpaths= space separated list of additional library paths
  • incpaths= add space separated list of additional header paths (for both Harbour and C)
  • instfiles= space separated list of values as in -instfile= option
  • instpaths= space separated list of values as in -instpath= option
  • prgflags= space separated list of values as in -prgflag= option
  • cflags= space separated list of values as in -cflag= option
  • resflags= space separated list of values as in -resflag= option
  • ldflags= space separated list of values as in -ldflag= option
  • ldflags+= space separated list of values as in -ldflag+= option
  • dflags= space separated list of values as in -dflag= option
  • dflags+= space separated list of values as in -dflag+= option
  • pflags= space separated list of values as in -pflag= option
  • psources= space separated list of values as in -pi= option
  • gui=<bool> ‘yes’ = -gui, ‘no’ = -std option
  • mt=<bool> ‘yes’ = -mt, ‘no’ = -st option
  • pic=<bool> ‘yes’ = -pic, ‘no’ = -pic- option
  • shared=<bool> ‘yes’ = -shared, ‘no’ = -static option
  • shareddef=<bool> similar to shared=, but works only if shared/static mode was not set before
  • fullstatic=<bool> ‘yes’ = -fullstatic, ‘no’ = -static option
  • debug=<bool> ‘yes’ = -debug, ‘no’ = -debug- option
  • optim= ‘yes’ = -optim, ‘no’ = -optim- option
  • nulrdd=<bool> ‘yes’ = -nulrdd, ‘no’ = -nulrdd- option
  • nodefgt=<bool> ‘yes’ = -nodefgt, ‘no’ = -nodefgt- option
  • map=<bool> ‘yes’ = -map, ‘no’ = -map- option
  • hbcppmm=<bool> ‘yes’ = -hbcpmm, ‘no’ = -hbcpmm- option
  • implib=<bool> ‘yes’ = -implib, ‘no’ = -implib- option
  • winuni=<bool> ‘yes’ = -winuni, ‘no’ = -winuni- option
  • strip=<bool> ‘yes’ = -strip, ‘no’ = -strip- option
  • run=<bool> ‘yes’ = -run, ‘no’ = -run- option
  • inc=<bool> ‘yes’ = -inc, ‘no’ = -inc- option
  • safe=<bool> ‘yes’ = -safe, ‘no’ = -safe- option
  • cpp= same as -cpp= option
  • warn= same as -warn= option
  • compr= same as -compr= option
  • head= same as -head= option
  • plugins= space separated list of hbmk2 plugins to load
  • gt=<name> same as -gt<name> option
  • gtdef=<name> set the default GT to be used
  • env= same as -env: option
  • deppkgname= same as -deppkgname= option
  • depkeyhead= same as -depkeyhead= option
  • depoptional= same as -depoptional= option
  • depcontrol= same as -depcontrol= option
  • depincroot= same as -depincroot= option
  • depincpath= same as -depincpath= option
  • depincpathlocal= same as -depincpathlocal= option
  • depimplibs= same as -depimplibs= option
  • depimplibd= same as -depimplibd= option
  • depfinish= same as -depfinish= option
  • name= package name
  • description= package description
  • version=<x.y.z> package version number, where x,y,z >= 0 <= 255. Defaults to 0.0.1, if not specified.
  • keywords= space separated list of keywords
  • licences= space separated list of licenses
  • repository= space separated list of source repository references

Plugin API:
(‘hbmk’ is the context variable received by the plugin entry function)

  • hbmk_Register_Input_File_Extension( hbmk, <cExt> ) -> NIL
    Register input file extension to be passed to plugin (by default all unknown file extensions are passed to Harbour compiler).
  • hbmk_AddInput_PRG( hbmk, <cFileName> ) -> NIL
    Add a Harbour input file to the project.
  • hbmk_AddInput_C( hbmk, <cFileName> ) -> NIL
    Add a C input file to the project.
  • hbmk_AddInput_CPP( hbmk, <cFileName> ) -> NIL
    Add a C++ input file to the project.
  • hbmk_AddInput_RC( hbmk, <cFileName> ) -> NIL
    Add a Windows resource input file to the project.
  • hbmk_AddInput_OBJ( hbmk, <cFileName> ) -> NIL
    Add a binary object file to the project.
  • hbmk_AddInput_INSTFILE( hbmk, <cFileName>, [<cGroup>] ) -> NIL
    Add a file to be installed, with an optional -instpath= group name.
  • hbmk_OutStd( hbmk, <cText> ) -> NIL
    Output text to stdout.
  • hbmk_OutErr( hbmk, <cText> ) -> NIL
    Output text to stderr.
  • hbmk_OutStdRaw( hbmk, … ) -> NIL
    Output text to stdout without any formatting.
  • hbmk_OutErrRaw( hbmk, … ) -> NIL
    Output text to stderr without any formatting.
  • hbmk_Macro( hbmk, <cMacro> ) -> <cResult>
    Evaluate hbmk2 macro expression.
  • hbmk_FNameEscape( hbmk, <cFileName> ) -> <cFileName>
    Escape/quote filename for using it as external command parameter.
  • hbmk_PathSepToTarget( hbmk, <cFileName> ) -> <cFileName>
    Convert filename to the format required for the target platform/C compiler.
  • hbmk_PathSepToForward( <cPath> ) -> <cPath>
    Convert filename to have forward slash directory separators.
  • hbmk_PathFromWorkdirToCWD( hbmk ) -> <cRelativePath>
    Return relative path of -workdir= value from current working directory.
  • hbmk_FindInPath( <cFileName>, [<xPath>], [<aExtDef>] ) -> <cFNFound> | NIL
    Find file in <xPath> (array or pathsep delimited string are accepted) with list of <aExtDef> alternate extensions (defaults to executable binaries). Returns filename if found and NIL if not.
  • hbmk_FNameDirExtSet( <cFileName>, [<cDirNew>], [<cExtNew>] ) -> <cFileName>
    Change directory and/or extension in filename.
  • hbmk_FuncNameEncode( <cFuncName> ) -> <cFuncNameEncoded>
    Encode function name according to Harbour compiler rules for forming HB_FUNC() function names in C code.
  • hbmk_StrStripQuote( <cString> ) -> <cString>
    Strip double quote enclosure from a string.
  • hbmk_ArrayToList( <aList>, [<cSeparator>] ) -> <cList>
    Convert array of strings to a string. Default separator is a single space.

Plugin variables:
(‘hbmk’ context hash items, case-sensitive, read-only unless marked otherwise)

  • “apiver” API version as an integer
  • “cSTATE” callback state. Can be: ‘init’, ‘pre_all’, ‘pre_prg’, ‘pre_res’, ‘pre_c’, ‘pre_link’, ‘pre_lib’, ‘pre_cleanup’, ‘post_build’, ‘post_all’
  • “params” array of parameters passed to plugins via -pflag=/pi= options or having an extension registered via hbmk_Register_Input_File_Extension()
  • “vars” hash of plugin custom variables. Writable, local to each plugin
  • “cPLAT” -plat value
  • “cCOMP” -comp value
  • “nCOMPVer” see HB_COMPILER_VER envvar
  • “cCPU” -cpu value
  • “cBUILD” -build= value
  • “cOUTPUTNAME” -o value
  • “cTARGETNAME” see ${hb_targetname} macro
  • “cTARGETTYPE” see ${hb_targettype} macro
  • “lREBUILD” -rebuild option status
  • “lCLEAN” -clean option status
  • “lDEBUG” -debug option status
  • “lMAP” -map option status
  • “lSTRIP” -strip option status
  • “lDONTEXEC” -traceonly option status
  • “lIGNOREERROR” -ignore option status
  • “lTRACE” -trace option status
  • “lQUIET” -q option status
  • “lINFO” -info option status
  • “lBEEP” -beep option status
  • “lRUN” -run option status
  • “lINC” -inc option status
  • “cCCPATH” see HB_CCPATH envvar
  • “cCCPREFIX” see HB_CCPREFIX envvar
  • “cCCSUFFIX” see HB_CCSUFFIX envvar
  • “cCCEXT” see HB_CCEXT envvar
  • “cWorkDir” -workdir= value
  • “nExitCode” Current exit code

Shell API available in Harbour scripts:

  • hbshell_gtSelect( [<cGT>] ) -> NIL
    Switch GT. Default [*]: ‘gtwin’
  • hbshell_Clipper() -> NIL
    Enable Clipper compatibility (non-Unicode) mode.
  • hbshell_include( <cHeader> ) -> <lSuccess>
    Load Harbour header.
  • hbshell_uninclude( <cHeader> ) -> <lSuccess>
    Unload Harbour header.
  • hbshell_include_list() -> NIL
    Display list of loaded Harbour header.
  • hbshell_ext_load( <cPackageName> ) -> <lSuccess>
    Load package. Similar to #request PP directive.
  • hbshell_ext_unload( <cPackageName> ) -> <lSuccess>
    Unload package.
  • hbshell_ext_get_list() -> <aPackages>
    List of loaded packages.
  • hbshell_DirBase() -> <cBaseDir>
    hb_DirBase() not mapped to script.
  • hbshell_ProgName() -> <cPath>
    hb_ProgName() not mapped to script.

Examples to start with hbmk2:

  • To run the interactive shell (‘dot’ prompt)
    $ hbmk2 .
  • To run a Harbour script
    $ hbmk2 myscript.hb [<parameter[s]>]

Examples to build and run Harbour portable binary (aka precompiled Harbour script):

  • To build
    $ hbmk2 -gh myscript.hb
  • To run result of above
    $ hbmk2 myscript.hrb [<parameter[s]>]

Examples to build a Harbour application:

  • To build one simple .prg
    $ hbmk2 hello.prg
  • To build multiple .prg sources into one application in incremental mode
    $ hbmk2 mymain.prg myfuncs.prg -inc
  • To build an application using a project file
    $ hbmk2 myapp.hbp
  • To build an application using incremental mode
    $ hbmk2 myapp.hbp -inc
  • To build an application which uses a contrib package or 3rd party (add-on) package that ships with an .hbc file
    $ hbmk2 myapp.prg hbct.hbc
  • To build an application which uses a raw library
    $ hbmk2 myapp.prg -lmylib -L<path_to_mylib>
  • To build an application which uses a Windows resource
    $ hbmk2 mymain.prg myres.rc
  • To build an application which links against Harbour dynamic libraries
    $ hbmk2 -shared myapp.prg
  • To build an application out of all .prg and .c sources residing in ‘source’ subdir
    $ hbmk2 -omyapp src/*.prg src/*.c

Examples to build a Harbour static library:

  • To build library ‘mylib’ from sources
    $ hbmk2 -hblib mylibsrc.prg -omylib
  • To build library ‘mylib’ from sources using incremental mode
    $ hbmk2 -hblib mylibsrc.prg -omylib -inc

Exit codes (“errorlevels”):

  • 0 no error
  • 1 unknown platform
  • 2 unknown compiler
  • 3 failed Harbour detection
  • 5 failed stub creation
  • 6 failed in compilation (Harbour, C compiler, Resource compiler)
  • 7 failed in final assembly (linker or library manager)
  • 8 unsupported
  • 9 failed to create working directory
  • 19 help
  • 10 dependency missing or disabled
  • 20 plugin initialization
  • 30 too deep nesting
  • 50 stop requested
  • <other> when -run option is used, the exit code will be the one returned by the target executable


  • <script> can be:
    <@script> or <script.hbm>: command-line options in file
    <script.hbp>: command-line options in file, it also marks a new build target if specified on the command-line
    <script.hbc>: package configuration file
  • Source filename without extension will load the .hbp file, if such .hbp file exists in current directory. If not, .prg extension will be used.
  • Multiple -l, -L, -i and <script> parameters are accepted.
  • Regular Harbour compiler options are also accepted as is.
    (see them with -harbourhelp option)
  • hbmk.hbc option file in hbmk2 directory is always processed if it exists. On *nix platforms ~/.harbour, /etc/harbour, <base>/etc/harbour, <base>/etc are checked (in that order) before the hbmk2 directory.
  • hbmk.hbm make script in current directory is always processed if it exists.
  • Using forwards slashes is recommended in option values as directory separator, but backslashes are also equally accepted.
  • Filters are accepted in each .hbc line and most options.
    Filters can be combined using ‘&’ (and), ‘|’ (or) operators, negated by ‘!’ operator and grouped by parentheses. Ex.: {win}, {gcc}, {linux|darwin}, {win&!pocc}, {(win|linux)&!watcom}, {unix&mt&gui}, -cflag={win}-DMYDEF, -stop{dos}, -stop{!allwin}
  • Most .hbc lines (libs=, hbcs=, prgflags=, cflags=, ldflags=, libpaths=, instfiles=, instpaths=, echo=) and corresponding command-line parameters will accept macro variables. libpaths= also accepts %{hb_name} which translates to the name of the .hbc file under search.
  • Options accepting macro variables also support command substitution. Enclose command inside “, and, if the command contains space, also enclose in double quotes. Standard output of the command will be used as the value. F.e. “-cflag=`wx-config –cflags`”, or ldflags={unix&gcc}”`wx-config –libs`”.
  • When multiple build target type selection options (-hblib, -hbdyn, etc.) are specified, the first one will be significant, the rest will be silently ignored.
  • Libraries and object files built with/for CA-Cl*pper will not work with any supported platform/compiler.
  • Defaults and feature support may vary by platform/compiler.
  • GNU Make or any C compiler specific make tool and MSYS (on Windows) are not needed to run hbmk2.
  • . (dot) passed as first parameter will enter the interactive Harbour shell.
  • .hb, .hrb or .dbf file passed as first parameter will be run as Harbour script. If the filename contains no path components, it will be searched in current working directory and in PATH. If not extension is given, .hb and .hrb extensions are searched, in that order. .dbf file will be opened automatically in shared mode and interactive Harbour shell launched. Non-standard extensions will be autodetected for source and precompiled script types. Note, for Harbour scripts, the codepage is set to UTF-8 by default. The default core header ‘hb.ch’ is automatically #included. The default date format is the ISO standard: yyyy-mm-dd. The default GT is ‘gtcgi’, unless full-screen CUI calls are detected, when ‘gtwin’ [*] is automatically selected (except for INIT PROCEDUREs).
  • You can use key <Alt+V> in interactive Harbour shell to paste text from the clipboard.
  • Values marked with [*] may be host platform and/or configuration dependent. This help was generated on ‘win’ host platform.

Supported <compiler> values for each supported <platform> value:

  • linux gcc, clang, icc, watcom, sunpro, open64
  • darwin gcc, clang, icc
  • win mingw, msvc, clang, bcc, bcc64, watcom, icc, pocc, xcc, mingw64, msvc64, msvcia64, iccia64, pocc64
  • wce mingwarm, mingw, msvcarm, poccarm
  • os2 gcc, gccomf, watcom
  • dos djgpp, watcom
  • bsd gcc, clang, pcc
  • hpux gcc
  • beos gcc
  • qnx gcc
  • android gcc, gccarm
  • vxworks gcc, diab
  • symbian gcc
  • cygwin gcc
  • minix clang, gcc
  • aix gcc
  • sunos gcc, sunpro


This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA (or visit
their web site at http://www.gnu.org/).

License extensions:
– This source code must be kept and distributed as part
of the Harbour package and/or the placement of the tool sources
and files must reflect that it is part of Harbour Project.
– Copyright information must always be presented by
projects including this tool or help text.
– Modified versions of the tool must clearly state this
fact on the copyright screen.
– Source code modifications shall always be made available
along with binaries.
– Help text and documentation is licensed under
Creative Commons Attribution-ShareAlike 3.0:


  • Viktor Szakáts (vszakats.net/harbour)

Source : https://github.com/harbour/core/blob/master/utils/hbmk2/doc/hbmk2.en.md

For further info :

FT Toolkit Overview

NANFOR.LIB Working Group G. Scott [71620,1521]
Overview UCLA
Version 2.1 October, 1992




This is a standard for establishing and maintaining NANFOR.LIB, a public-domain, user-supported library of functions designed to interface with Computer Associates CA-Clipper, version 5.01a, and later. You are encouraged to read it over and forward comments to Glenn Scott, CIS ID [71620,1521].

1.1 History

In October and November of 1990, a discussion on the evolution of third-party products, vendors, and marketing took place on the CompuServe Information Service’s Nantucket Forum (NANFORUM). During this discussion, a forum subscriber named Alexander Santic suggested the idea of a user-supported Clipper function library, available to all on the CompuServe Information Service (CIS). A number of subscribers, including several Clipper third party developers, and some Nantucket employees, expressed their support. This standard was a first step toward organizing such an endeavor.

Release 1.0 of the toolkit was made available in April, 1991 and had nearly 150 functions. By the time version 2.0 was released in August, 1991, the 1.0 library had been downloaded nearly 700 times by CompuServe users. By October of 1992, release 2.0 had been downloaded over 2100 times. The source code had been downloaded nearly 1500 times. In addition, release 2.0 was placed on the massive Internet archive site called SIMTEL20 where it was downloaded by CA- Clipper users worldwide. Over the course of the year that release 2.0 was available, seven patches were issued, each one gathering nearly 1000 downloads.

Computer Associates International, Inc. acquired Nantucket in the summer of 1992 and subsequently renamed NANFORUM to simply CLIPPER. In addition, the Clipper product itself was renamed to CA-CLIPPER. Despite the name changes, forum members decided to keep the toolkit’s name as “The Nanforum Toolkit,” partly for nostalgia. References to NANFORUM in this RFC have been replaced with CLIPPER.

1.2 Trademarks

CA-Clipper is a registered trademark of Computer Associates International, Inc. Computer Associates will be referred to as CA throughout this document.

1.3 Relationship to CA and third party

NANFOR.LIB is a project independent of any third party developer or CA. There is no official “sanction” or “seal of approval” from CA of any kind. In addition, NANFOR.LIB routines will be accepted and included without regard for whether or not routines performing a similar function are included in a commercial third party or CA product.

It is desired that NANFOR.LIB not compete with third party products but rather fill in the holes in CA-Clipper’s standard library. However, there will be some overlap into commercial third-party library functions, so it would be best if this is never taken into consideration when deciding on including a particular function.

Developers submitting NANFOR.LIB routines can and will be corporate developers, third party developers, independent consultant / programmers, hobbyists, and other CA-Clipper people. Perhaps even CA employees will contribute. No one is excluded or included due to any particular affiliation.

CA employees submitting functions are doing so as individuals, and are not making a policy of involving CA in the project, nor are they committing CA to supporting the public domain library.

1.4 CA-Clipper version supported

NANFOR.LIB functions, no matter what language they are written in, will be designed to work with CA-Clipper version 5.01a and later. Many of the functions, particularly those that use the EXTEND system, will be compatible with the Summer 1987 version of CA-Clipper. However, ensuring Summer 87 compatibility will be the responsibility of the user. If a user wants a function to work with Summer 87, she will have to modify the code herself if necessary. In many cases, this is a trivial task.

1.5 Queries from new users

Queries from new users interested in finding NANFOR.LIB should be handled in a uniform and courteous way. A short text file will be created that will briefly explain NANFOR.LIB, who the current people maintaining it are, and how to get a hold of it. This text message can be sent in response to any query. TAPCIS users will find this method very easy to implement.


2.1 Public Domain

NANFOR.LIB, its source code, and documentation will be public-domain software. It is not for “sale”, and shall not be sold. No fee or contribution of any kind will be required for anyone wanting a copy, other than what they would normally pay to download it from CompuServe. Users will be encouraged to submit functions via CompuServe.

2.2 Official repository

It is possible that copies of NANFOR.LIB will be downloaded and distributed elsewhere. This is encouraged, but the only copy of NANFOR.LIB and all associated documentation that will be maintained by volunteers is in an appropriate library on the CIS CLIPPER Forum.

2.2.1 Contents

The deliverables that make up the official posting on CompuServe shall be: NFLIB.ZIP

This will contain the files NANFOR.LIB (library), and NANFOR.NG (Norton Guide). NFSRC.ZIP

This will contain all the library source code, makefile, and other source-code related materials. NFINQ.TXT

This is a short text file used as a response to new user queries (see paragraph 1.5) NFRFC.ZIP

This contains an ASCII format, as well as a WordPerfect 5.1 format copy of NANFOR.RFC named NFRFC.TXT (ASCII) and NFRFC.WP5 (WordPerfect 5.1). NFHDRS.ZIP

This contains templates of the file and documentation header blocks, including a sample, for prospective authors (FTHDR.PRG, FTHDR.ASM, FTHDR.SAM) PATx.ZIP

These are patch files (see paragraph 4.5.1).


3.1 “Best Function”

It is possible that more than one developer will submit a function or package of functions that perform substantially the same services. In that event, the referees will choose one to be included based on power, functionality, flexibility, and ease of use. Due to the cooperative, non-commercial nature of the library, no one’s feelings should be hurt by excluding duplicate functions.

In addition, it is possible that two substantially similar functions or packages will benefit from merging them together to provide new functionality. This will be the prerogative of the referees (see paragraph 6.3), in close consultation with the authors.

3.2 Public Domain

Each author submitting source code must include as part of that code a statement that this is an original work and that he or she is placing the code into the public domain. The librarian (see paragraph 6.1) and referees should make a reasonable effort to be sure no copyrighted source code, such as that supplied with some third party libraries, makes it into NANFOR.LIB. However, under no circumstances will the librarian, referees, or any other party other than the submitter be responsible for copyrighted code making it into the library accidentally.

3.3 Source code

Full source code must be provided by the author for every routine to be included in NANFOR.LIB. No routine, no matter what language, will be put into the library on the basis of submitted object code.

3.4 Proper submission

Due to the volume of submissions expected, librarians and referees may not have the time to fix inconsistencies in documentation format, function naming, and other requirements. Therefore, the librarian shall expect source code to arrive in proper format before proceeding further with it.

3.5 Quality and perceived usefulness

In a cooperative effort like this, it is very difficult to enforce some standard of quality and/or usefulness. For example, a package of functions to handle the military’s “Zulu time” may be very useful to some, and unnecessary to others.

The Nanforum Toolkit will by its very nature be a hodgepodge of routines, some of very high quality, some not so high. It is up to the users to improve it. It will be complete in some areas and vastly inadequate in others. It is up to the users to fill in the holes.

We shall err on the side of including “questionable” functions, provided they seem to work. Debates on the quality of the library’s source code shall be encouraged and will take place in the proper message section of the CompuServe CLIPPER forum.


4.1 Selection procedure

Source code will be submitted to the librarian, the documenter (see paragraph 6.2), or one of the referees. Code will be added if it has been reviewed, and approved by at least one, but preferably two, referees.

Code not meeting the documentation or source code formatting standards will generally be returned to the author with instructions.

Referees will test the submitted code. When the referees have finished evaluating a submission, they will report their approval or disapproval to the librarian, with comments.

Every effort should be made to make sure that the C and ASM functions are reviewed by referees with suitable C and ASM experience.

4.2 Update interval

As new functions are submitted, they will added to the library, and the documentation updated. Because this is a volunteer project, and because of the complexity involved in coordinating testing, documentation, and delivery, there will be no fixed interval for updates.

4.3 Version control

NANFOR.LIB will use a numeric version number as follows:

The major version will be numeric, starting from 1. This will change with each quarterly update. The minor version will change with each bug fix. This will start with zero and continue until the next major update, at which point it will revert to zero again.

Typical version numbers might be 1.1, 2.12, 15.2, etc.

The .LIB file, and all associated files, will carry a date stamp corresponding to the day it is released on the CLIPPER forum. The file time stamps shall correspond to the version number (i.e., 1:03am is version 1.3).

4.4 Announcing updates

As the library and its associated documentation are updated, simple announcements will be posted on the CLIPPER forum. This is the only place where an update shall be announced. An update will be announced after it has been successfully uploaded to the appropriate library on CompuServe.

4.5 Bug reports and fixes

The librarian will correlate and verify all bug reports, with the help of the referees. If the referees believe a bug to be serious, they will fix it and the librarian will release a maintenance upgrade immediately. If they consider it a minor bug, they will fix it but wait for the next scheduled upgrade to release it. In this case, a bug fix may be released as a “Patch.”

4.5.1 Patches

A “patch” is simply an ASCII text file containing instructions for editing the source code to a misbehaving function or group of functions. Patches may appear in the CIS library before a maintenance release or quarterly upgrade. A patch file will have a name of the form


where <n> is a number starting from 1. Patches will be numbered sequentially. Patches will be deleted every time a new version of NANFOR.LIB goes on-line.

A patch zipfile may optionally contain .OBJ files to be replaced in user libraries via a LIB utility.

4.6 Technical Support

Technical support will work just as any technical subject on the CompuServe CLIPPER forum works. Users will post questions and suggestions to a particular message area or thread, and anyone who knows the answer should respond. No one is obliged to answer, but it is considered good form to respond with something, even if one doesn’t know the answer.

Support will include help on recompiling the routines or modifying the source.

4.7 Linker Compatibility

In order to assist users of CA-Clipper third party linkers (such as WarpLink or Blinker), NANFOR.LIB may need to broken up into root and overlay sections. How this will be done will be determined when splitting becomes necessary.

The librarian is not responsible for testing every possible linker for NANFOR.LIB compatibility. It is hoped that linker users will submit appropriate link scripts or other documentation for posting in the appropriate section on the CLIPPER forum.

4.8 Splitting NANFOR.LIB by functional category

It is possible that at some future date, it will make sense to split NANFOR.LIB into separate functional areas (e.g., video routines vs. date routines, etc). This RFC will be modified accordingly should that need arise.


The goal of this standard is not to force anyone to rewrite his code for this library, but to create some consistency among the functions so that they may more easily maintained and understood by all CA-Clipper developers, both novice and advanced.

However, it is extremely important that anyone submitting code attach the proper headers and documentation and fill them out correctly. This will make it much easier for code to be added to the library.

5.1 Required sections for each function
5.1.1 Header (author name/etc, version ctrl info)

Figure 1 shows a header that must be included at the top of every piece of source code submitted to the library. This header will work with both CA-Clipper and C code. For ASM code, substitute each asterisk (“*”) with a semicolon (“;”) and delete the slashes (“/”).

 * File......:
 * Author....:
 * CIS ID....: x, x
 * Date......: $Date$
 * Revision..: $Revision$
 * Log file..: $Logfile$
 * Modification history:
 * ---------------------
 * $Log$
Figure 1 - Standard function header.

Note that the date, revision, logfile, and modification history fields will be maintained by the librarian and should not be edited or adjusted by code authors.

The “File” field shall contain the source file name. This is often independent of the individual function name. For example, a function named ft_screen() would be included in SCREEN.PRG. As a rule, source files (.PRG, .C, .ASM) should not have the “FT” prefix.

The “Author” field should have the author’s full name, and CIS number. A CIS number is important, as this will make bug fixing and other correspondence easier.

5.1.2 Public domain disclaimer

Authors shall simply state “This is an original work by [Author’s name] and is hereby placed in the public domain.”

5.1.3 Documentation block
/* $DOC$
 * $END$

Figure 2 – Standard Documentation Header

The documentation block must be carefully formatted as it is used by the documenter to produce the Norton Guide documentation for the library.

The keywords enclosed in dollar-signs delimit sections of the documentation header analogous to those in the CA-Clipper 5.0 documentation. Documentation should be written in the same style and flavor as the CA material, if possible. Refer to the CA-Clipper documentation for more detail and numerous examples.

The documentation will appear on comment lines between the keywords. Examples are optional. Do not put documentation on the same line as the comment keyword.

Note that the $DOC$ and $END$ keywords serve as delimiters. Do not place any text between $DOC$ and $FUNCNAME$, or any documentation after the $END$ keyword, unless that documentation belongs in the source code file and not in the resultant Norton Guide file.

The $FUNCNAME$ keyword should be followed by the function name, with parentheses, and no arguments or syntax, such as:


Note the indent for readability. Parentheses shall be added after the function name as shown above.

The $ONELINER$ keyword should be followed by a simple statement expressing what the function does, phrased in the form of a command, e.g.:

          Sum the values in an array

The length of the entire $ONELINER$ shall not exceed 60 characters (this is a Norton Guide limitation).

The $SYNTAX$ keyword should be followed by a CA- standard syntax specifier, such as:

         ft_screen( <nTop> [,<nBottom>] ) -> NIL

All parameters have proper prefixes (see paragraph 5.4), and are enclosed in <angle brackets>. Optional parameters are enclosed in [square brackets] as well. An arrow should follow, pointing to the return value. If there is no return value, it should be NIL. Any others should be preceded with the proper prefix (see the CA- Clipper documentation).

The $SEEALSO$ field provides a way to generate cross-references in the Norton Guide help documentation. Use it to point the user to other related functions in the forum toolkit. For example, if ft_func1() is also related to ft_func2() and ft_func3(), the field would look like this:

ft_func2() ft_func3()

Note that fields are separated by spaces and the parentheses are included.

The $INCLUDE$ area allows you to specify what files are included by this function (this will be used to organize the on-line help file, and possibly the master makefile). An example would be

int86.ch int86.inc

Other documentation fields should be self- explanatory. Review the appendix for a sample. All fields are required and must be filled in. Examples should not be considered optional.

5.1.4 Sample header and documentation block

Refer to the Appendix for a sample header and documentation block.

5.1.5 Test driver

A test driver is an optional section of C or CA- Clipper code that will only be compiled under certain circumstances. Developers are encouraged to include a short “test section” in front of their code.

The test driver shall be surrounded by the following pre-processor directives, and placed at the top of the source file:

#ifdef FT_TEST
     [test code]

The test driver is currently optional, but authors submitting Clipper code should seriously consider adding it. It is a good way to include short demos within a piece of source code, yet pay no penalty because it is only compiled if needed. It will be invoked when a #define is created that says “#define FT_TEST.” This is a way for submitters to include short test routines with their functions and yet keep it all in one source file. This will be useful to end users.

This test driver may become required in a future version of the RFC.

5.1.6 Code

The source code shall be formatted as described in paragraph 5.4.

5.2 Function names

All NANFOR.LIB functions start with one of two prefixes. If the function is to be called by user programs, then it will begin with the prefix

FT_       ("F", "T", underscore)

Note that “FT” is a mnemonic for “Forum Toolkit.” If the function is “internal” to a module, then it will be prefixed by an underscore:

_FT ( Underscore, "F", "T" )

with no trailing underscore. Examples:

FT_CURDIR() "external"
_ftAlloc() "internal"
5.3 Librarian’s authority to change function names

Some functions will be submitted that either (1) bear a similar name to another function in the library, or (2) bear an inappropriate name. For example, a function called FT_PRINT that writes a character to the screen could be said to be named inappropriately, as a name like FT_PRINT implies some relationship to a printer. The librarian shall have the responsibility to rename submitted functions for clarity and uniqueness.

5.3.1 Changing a function name after it has been released

Once the library is released with a particular function included, then a function name should generally be frozen and not renamed. To do so would probably cause difficulties with users who had used the previous name and are not tracking the changes to the library.

5.4 Source code formatting
5.4.1 Clipper

Clipper code shall be formatted in accordance with CA’s currently defined publishing standard. Although there will surely be some debate over whether this is a good idea, in general, the goal is to provide something consistent that all CA- Clipper developers will recognize.

Minor deviations will be permitted.

The CA standard usually means uppercase keywords, and manifest constants, and lower case everything else.

In addition, identifiers shall be preceded with the proper metasymbol:

 n Numeric
 c Character or string
 a Array
 l Logical, or boolean
 d Date
 m Memo
 o Object
 b Code block
 h Handle
 x Ambiguous type

Refer to the CA-Clipper documentation for samples of CA’s code publishing format.

5.4.2 C

C source code shall be formatted in a generally accepted way, such as Kernighan and Ritchie’s style used in the book _The C Programming Language_.” The use of CA’s EXTEND.H is encouraged.

5.4.3 ASM

No particular formatting conventions are required for assembly language source code, since assembly code formatting is fairly standard. Lowercase code is preferred. Be sure to include the proper documentation header information, as described above.

Do not place ASM code in DGROUP. See paragraph 5.11.

5.5 Organization into .PRGs

Since many different people will be submitting routines, it is probably best if all routines that belong together are housed in the same .PRG. If there is some reason to split the .PRG, the referees and the librarian will handle that as part of library organization.

5.6 Header files

Including a “.ch” or “.h” or “.inc” file with each function would get unwieldy. For the purpose of NANFOR.LIB, all #defines, #ifdefs, #commands, #translates, etc that belong to a particular source file shall be included at the top of that source file. Since few submissions will split over multiple source files, there will usually be no need to #include a header in more than one place.

If a “ch” file will make the end user’s job of supplying parameters and other information to NANFOR.LIB functions easier, then it shall be submitted as a separate entity. The referees will decide on whether to include these directives in a master NANFOR.CH file.

5.7 Clipper 5.0 Lexical Scoping

NANFOR.LIB routines that are written in CA-Clipper will make use of CA-Clipper 5.0’s lexical scoping features to insulate themselves from the rest of the user’s application.

For example, all “privates” shall generally be declared “local.”

If a package of Clipper functions is added to the library, then the lower-level, support functions will be declared STATIC as necessary.

5.8 Use of Publics

Authors shall not use PUBLIC variables in NANFOR.LIB functions, due to the potential interference with an end-user’s application or vice versa.

If a global is required for a particular function or package of functions, that global shall be accessed through a function call interface defined by the author (.e.g, “ft_setglobal()”, “ft_getglobal()”, and so on). Globals such as these shall be declared static in the .PRG that needs them.

5.9 Use of Macros (“&” operator)

The use of macros in NANFOR.LIB functions will be, for the most part, unnecessary. Since this is a CA-Clipper 5.0 library, the new 5.0 codeblock construct should be used instead. Anyone having trouble figuring out how to convert a macro to a codeblock should post suitable questions on the CLIPPER forum on CompuServe.

5.10 Use of Static Functions

Any CA-Clipper 5.0 function that is only needed within the scope of one source file shall be declared STATIC. This applies mostly to NANFOR.LIB “internals” (names with an “_ft” prefix) that user programs need not access.

5.11 Use of DGROUP in ASM Functions

Use of DGROUP in assembly language functions shall be avoided, in accordance with CA’s recommendations. Assembly functions written for NANFOR.LIB shall use a segment named _NanFor, as in the following example:

Public FT_ChDir
Extrn _ftDir:Far
Segment _NanFor Word Public "CODE"
 Assume CS:_NanFor
Proc FT_ChDir Far
 Endp FT_ChDir
 Ends _NanFor
5.12 Use of "Internals"

Use of CA-Clipper “internals” by code authors is allowed. However, should any code make use of an internal, i.e., a function or variable that is not part of the published CA-Clipper API, then that internal shall be clearly marked in the documentation (under “DESCRIPTION”) and in the actual code, everywhere the internal is used.

5.13 Procedures for compiling functions
5.13.1 Clipper

Clipper functions will be compiled under the current release of CA-Clipper 5.0, with the following compiler options:

/n /w /l /r

Note that neither line numbers nor debugging information will find its way into NANFOR.LIB, to keep the code size down. End users may recompile NANFOR.LIB with these options enabled if they want to view NANFOR.LIB source in the debugger.

5.13.2 ASM

Assembly functions must compile successfully under any MSDOS assembler capable of producing the proper .OBJ file. However, care should be taken not to use any macros or special syntax particular to one vendor’s assembler, because that would make it difficult for end users to recompile the source. The preferred assembler is MASM, followed by TASM.

5.13.3 C

C functions must compile successfully under any C compiler capable of interfacing to CA-Clipper. Obviously, Microsoft C, version 5.1, is the preferred development environment. Care should be taken, when writing C code, not to use any special compiler features particular to one vendor’s C compiler, because that would make it difficult for end users to recompile the source.

5.14 Functions requiring other libraries

It is very easy to write functions in C that call the compiler’s standard C library functions. However, NANFOR.LIB can make no assumptions about the end user’s ability to link in the standard library or any other library. Therefore, no function will be added to NANFOR.LIB that requires any other third party or compiler manufacturer’s library.


6.1 Librarian

The librarian will be the person who rebuilds the library from the sources and uploads the resulting deliverables to the proper CLIPPER forum library on CompuServe. The librarian generally does *not* test code or edit source code to repair formatting errors.

6.2 Documenter

The documenter is responsible for maintaining the Norton and guides and keeping it in sync with each new release.

6.3 Referees

Referees are volunteers who read source code, clean it up, compile it, look for problems like potentially problematic C code, decide on which function is best, consolidate common functions, etc. They make sure the header and documentation blocks are present. There is no election or term for refereedom. One simply performs the task as long as one can and bows out when necessary.

6.4 Transitions

Not everyone will be able to stay around forever to keep working on this project. Therefore, it is the responsibility of each referee, documenter, or librarian to announce as far in advance as possible his or her intention to leave, in order to give everyone a chance to come up with a suitable replacement. Don’t let it die!


Current contributors, directly and indirectly, to this document include:

Don Caton [71067,1350]
Bill Christison [72247,3642]
Robert DiFalco [71610,1705]
Paul Ferrara [76702,556]
David Husnian [76064,1535]
Ted Means [73067,3332]
Alexander Santic [71327,2436]
Glenn Scott [71620,1521]
Keith Wire [73760,2427]
Craig Yellick [76247,541]
James Zack [75410,1567]


  • In Harbour library file name of NanForum Toolkit is hbnf.a
  • Maybe some functions :
    • obsoleted,
    • used some low-level hardware access or some OS specific features,
    • so not included in hbnf library.