Development Environment (Worldgroup 3.x)

Applies to: v10

This chapter describes the Worldgroup 3.x tool chain (Borland C++ 5.00, \WGDEV, .MAK files, MKNT, Visual C++ 4.2, Visual Basic 3.00). It is not the v10 environment. v10 uses Visual Studio projects (chapter 29, section 29.3). Sections that name Borland .MAK macros, BC50, MAKEWGS, 16-bit batch files or Visual Basic are history; the Active HTML passages are marked Not in v10 below.

Applies to: WG3.x

Editor's note: this chapter is new in the WG3 layer. It is from section 1-3 ("Overview", "Development Tools", "Development Environment Changes") of the Developer's Addendum for Worldgroup 3.12 (wg312dev; the earlier 3.10 edition, devad3, is the same text apart from "3.10" for "3.12", BC5 for BC50, InstallShield V5.0 for V5.1 and spelling). The addendum has no figures. Prose is unrewritten; "Header check" notes record where the printed text disagrees with the WG3.2 headers. It replaces the WG1 development environment of chapters 1 and 2 (Borland C++ 4.50, Phar Lap 286, %MBBS%). Paragraphs about client programs are tagged WG1-3.x (Client) and the Active HTML paragraphs WG3.x only.

Overview

Worldgroup 3.12 incorporates many changes to the development environment. Several new environment variables are used to make compilation of your projects easier. As the development of Worldgroup 3.12 progressed, it became evident that the existing Major BBS development environment was lacking in several places, most notably, every project being in one directory. What follows is everything that has changed since the last release of the Major BBS development environment.

Development Tools

Galacticomm only supports Borland C++ 5.00 for re-compiling source code for both DOS and NT/95 servers.

Applies to: WG3.x

Header check: the kit also ships bc551-32.mak (ilink32), keyed on the same BC50 variable (WGDEV/SRC/bc551-32.mak:4-13), alongside bc50-32.mak, bc45.mak and bc31.mak; the addendum names only 5.00.

Galacticomm only supports Microsoft Visual C++ 4.2 for re-compiling offline programs for NT/95.

Applies to: WG1-3.x (Client)

The Visual Basic 3.00 requirement (and the VB3 variable, MK31V/MK31W, MKVB below) concerns client programs, which span WG1-3.x.

Galacticomm only supports Microsoft Visual Basic 3.00 for re-compiling client side programs.

Development Environment Changes

With the advent of WebCast ProServer and ActiBase Server, it was clear our development environment needed an overhaul. Most notably, we needed to be able to #ifdef more than just MSG, DEF, and BCR files. Also, we could not be limited to #ifdef GCWINNT or #ifdef GCDOS. This realization resulted in the re-organization of the development environment and separating of each individual project into a directory of its own.

File Naming Conventions

Our DOS projects still adhere to the 8.3 naming conventions. However, you may find that some of our NT/95 only projects contain files that do not adhere to the 8.3 conventions.

Worldgroup Development Environment Requirements

This version of the Major BBS Developers Kit requires a Windows 32 bit environment. Every developer utility is compiled for WIN32 and they all support long filenames.

Environment Variables

Variable Meaning
BC50 Root directory of the Borland C++ 5.0 directory (C:\BC5)
DOSEXT Root directory of the DOS Extender for the DOS Environment (C:\RUN286)
WGDEV Root directory of the Major BBS development environment (C:\WGDEV)
WGDOS Root directory of the Worldgroup DOS runtime (C:\WGSERV)
WGNT Root directory of the Worldgroup NT/95 runtime (C:\WGSERVNT)
BUDOS Used to create VIR files for the DOS environment (Explained later in this document)
MVC42 Root directory of Microsoft Visual C++ 4.2 projects (C:\MSDEV)
VB3 Root directory of Visual Basic 3.0 (C:\VB)

Applies to: WG1-3.x (Client)

The VB3 variable (Visual Basic 3.0 root) concerns client programs; the other variables are WG3.x.

Development/Runtime Tree

Directory                               Description/What is contained in them

- WGDEV                         Main development directory
        - INC                           Shared header files
        - BIN                           Development executables and batch files
                                        (formerly WGTOOLS)
        - LIB                           DEF files and all shared LIB files
        - HELP                          Developer documentation
        - SRC                           Source code broken down into single projects
        - VCPROJ                        Microsoft Visual C++ projects

The \WGDEV\SRC directory

Applies to: WG3.x

Header check: ICSRC is where the Active HTML kernel lives (icsrc\galacth, header GALACTH.H) and the Active HTML ("ah") applications are in APPS (galfilah, galpnqah, galregah); see the Active HTML note under "Files contained in each project". The kit has three more top-level SRC directories than the addendum lists: experimental, faxsrc and insutils; UTILS, OFFLINE, REBUILD and WGSERVER sit under SERVER, as the indentation shows.

The most notable change to the development environment is in the source directories. Formerly \WGDEV\WGSRC, this directory was renamed and separated into multiple projects. The new directory structure under \WGDEV\SRC looks like this:

Directory                               Description/What is contained in them

- \WGDEV\SRC                            Source directory
        - API                           (gcommlib, galme, galsmb...)
        - APPS                          (galfil, galpnq, galrsy, galreg...)
        - DEBUG                 (galdebug, galdebgcg...)
        - ICSRC                         (galtnt, galtcpip, galftp...)
        - SERVER
                - WGSERVER              (wgserver, wgsignup, galsupah...)
                - UTILS                 (wgsdraw, wgsmtree, wgsfndo...)
                - OFFLINE               (wgscmaps, wgscolor, wgsmref...)
                - REBUILD               (wgsrbk, wgsrbt...)
        - DEVUTILS                      (galcopy, galport, galprod...)

PATH Statement

Applies to: WG3.x

Header check: the statement that \WGDEV\WGTOOLS "no longer exists" does not match the 3.2 kit, which still has a \WGDEV\WGTOOLS directory (THEDRAW.*, WGSSYNC, BTRIEVE). Command-line tools are in \WGDEV\BIN; keep that entry on the PATH.

The \WGDEV\WGTOOLS directory no longer exists. Instead, your path statement should be changed to include \WGDEV\BIN.

Files contained in each project

Applies to: WG3.x only (Active HTML)

The .HTML, .GIF and .JPG files named here belong to the Active HTML web layer (GALACTH.H, icsrc\galacth), which first ships in WG3.x. The addendum does not otherwise document Active HTML; the headers GALACTH.H, DNF.H and DNFMGR.H are the only reference (acthVersion "ActiveHTML/1.0".."1.2", GALACTH.H:22-26).

Applies to: v10

Not in v10. Active HTML is not supported in v10 (MBBS10.txt section 2: "mainly because the C++ code has yet to be ported"; it "may return" or be replaced by a React/HTMX front end with WebSockets). The v10 headers compile the Active HTML declarations out (#ifdef SUPPORTREMOVED //AHTML and C/S Support removed, tlc.h:112-120); GALACTH.H is still in inc/, so its presence says nothing about support.

Each project directory contains ALL files pertaining to that project (this includes all source: .C and .H, .MSG, .DEF, .BCR, .HTML, .GIF, and .JPG). As part of the compilation (mknt, mkdosp...), each .MAK file compiles/copies files to their proper build directories, most of this being automated by GCRULES.MAK. Files that are shared in multiple projects appear in both projects. Common .H files appear in their project as well as \WGDEV\INC. Common .DEF files appear in their project and \WGDEV\LIB. This may seem like a large undertaking, however, using version control to track source files simplifies this process.

#ifdef’ing files

Worldgroup 3.00 allowed you to #ifdef .MSG, .DEF, and .BCR files, and the utility WGSSYNC.EXE parsed these files during compilation. However, you were only allowed to use GCWINNT and GCDOS for defines. With Worldgroup 3.12, you can now #ifdef .MDF, .MSG, .HTM, .CVT, and .DMD. Additional files may be added on a per-project basis. You are no longer limited to using GCWINNT or GCDOS. Any #ifdef you use in source code may also be used in the parse files. For a description of the limitations of #ifdef’ing files, please see the section on GALPARSE.EXE under New Development Utilities.

Making Worldgroup 3.00 .MAK files work for 3.12

Minor changes are required in order for Worldgroup 3.00 .MAK files to work under the new environment. The following is a step by step list of what needs to change:

1. The line !include $(WGDEV)\wgsrc\GCRULES.MAK needs to be replaced with !include $(WGDEV)\src\GCRULES.MAK.

2. Any references to SRCDIR and SRCDIROS should be removed. All files for projects are contained in the project directory. There is no need for these macros anymore.

3. The $(MODEL) macro for DOS compilations now gets set to “LARGE” or “PHARLAP” instead of “L” or “P”.

4. Any references to the $(CC) macro should be changed to $(PARSEOPTS). The $(PARSEOPTS) macro is passed on to the GALPARSE.EXE which is described later in this document.

5. All references to $(DLIBDIROS) should be removed. GCRULES.MAK defines where all .LIB files are located.

6. All CD commands should be removed from the make procedure. There should be no reason to change directories. GCRULES.MAK has all paths set up correctly.

7. If your project contains a .DEF file, the line that has DEFILE = (file) needs to be changed to DEFILE = $(TEMPDIR)\file). Your .DEF file in your project can now contain #ifdef’s. As part of the $(GCBUILD) macro, your .DEF files are parsed to $(TEMPDIR).

8. There is a new macro that needs to be added to the beginning of the dependencies list. $(GCBUILD) forces all pre-build parsing to take place. The $(GCBUILD) macro can be found inside of GCRULES.MAK in the \wgdev\src directory and is discussed later in this document.

9. The $(GCBUILD) is a dependency of your project that always changes. Because of this, every time you re-compile, the make utility thinks something has changed, and forces a re-link. To solve this problem, do the following:

Instead of having:

galfil.dll:                     \
        $(GCBUILD)              \
        galfil.h                \
        $(OBJFILES)    ...

Do the following:

start:                          \
        $(GCBUILD)              \
        galfil.dll

galfil.dll:                     \
        galfil.h                        \
        $(OBJFILES)     ...

The following is the Worldgroup 3.00 .MAK file for Cross-Wordz, followed by the changes required for this .MAK file to work properly in the 3.12 environment:

#################################################################
#  This makefile generates TTICWD.DLL                                   #
#################################################################
!include $(WGDEV)\wgsrc\GCRULES.MAK

SRCDIR = $(WGDEV)\cwdsrc
SRCDIROS = $(SRCDIR)\$(OS)

!if $(OS) == DOS
!       if $(MODEL) == L
!               error TTICWD not supported in Large Module Under DOS!
!       endif
!endif

DLLLIB =                                \
        $(DLLLIB)                       \
        $(DLIBDIROS)\wgserver.lib       \
        $(DLIBDIROS)\galgsbl.lib

OBJFILES =                              \
        tticwd.OBJ                      \
        cscwd.OBJ                       \
        cwdboth.OBJ

tticwd.dll:                                                     \
        tticwd.h                                                        \
        $(OBJFILES) $(DLLLIB) $(DLIBDIROS)\$(DEFILE)
        CD $(OBJDIR)
        $(LINK) $(LIBCMD) @&&|
$(PRODLL) $(OBJFILES)
$(RUNDIR)\$&
$(RUNDIR)\$&
$(DLLLIB) $(LINKDLL)
$(DLIBDIROS)\$(DEFILE)
|
        CD $(RUNDIR)

This is what the Worldgroup 3.12 version of the .MAK file looks like, with the changes highlighted:

#################################################################
#  This makefile generates TTICWD.DLL                                   #
#################################################################
!include $(WGDEV)\src\GCRULES.MAK

!if $(OS) == DOS
!       if $(MODEL) == LARGE
!               error TTICWD not supported in Large Module Under DOS!
!       endif
!endif

DLLLIB =                \
        $(DLLLIB)       \
        wgserver.lib    \
        galgsbl.lib

OBJFILES =              \
        tticwd.OBJ      \
        cscwd.OBJ       \
        cwdboth.OBJ

start:                  \
        $(GCBUILD)      \
        tticwd.dll

tticwd.dll:             \
        tticwd.h                \
        $(OBJFILES)     \
        $(DLLLIB)       \
        $(DEFILE)
        $(LINK) $(LIBCMD) @&&|
$(PRODLL) $(OBJFILES)
$(RUNDIR)\$&
$(RUNDIR)\$&
$(DLLLIB) $(LINKDLL)
$(DEFILE)
|

Editor’s note: in the original manual the items that changed in the 3.12 file are printed in bold: src in the !include line, LARGE, and the three added lines start: \, $(GCBUILD) \ and tticwd.dll. Bold cannot be shown inside a code block here; compare the two listings.

New .MAK file macros

The following is a list of new macros you may use in your .MAK files to make building projects easier:

CVTFILDIR - The directory to parse .CVT files to. Defaults to $(RUNDIR)\wgsdfcvt

Applies to: WG3.x only (Active HTML)

HTMLDIR and GIFDIR are Active HTML macros.

Applies to: v10

Not in v10. Active HTML is not supported in v10 (MBBS10.txt section 2: "mainly because the C++ code has yet to be ported"; it "may return" or be replaced by a React/HTMX front end with WebSockets). The v10 headers compile the Active HTML declarations out (#ifdef SUPPORTREMOVED //AHTML and C/S Support removed, tlc.h:112-120); GALACTH.H is still in inc/, so its presence says nothing about support.

HTMLDIR - Directory to parse .HTM files to. Defaults to $(RUNDIR)\webpages, however, for an ActiveH project such as File Libraries, you may change this to $(RUNDIR)\galacth\galfilah.

GIFDIR - Directory to copy all .GIF and .JPG files to. Defaults to $(RUNDIR)\webages\images.

Applies to: WG3.x

Header check: the default is spelled $(RUNDIR)\webpages\images in GCRULES.MAK:103; "webages" above is a typo in the addendum. CVTFILDIR, HTMLDIR and GIFDIR are all defined in GCRULES.MAK.

The $(GCBUILD) macro and GCBUILD directories

This macro expands to the filename tmpbld.bld. This file is a dependency in every project that forces certain events to occur for every compilation. Its main function is to track the list of $(PARSEOPTS) used for the last compilation and force a rebuild of the entire project if the list differs from compilation to compilation. Having code compile in many different ways through the use of #ifdef’s is great, however, if you compile something one way, then turn around and compile with a different set of #ifdef’s, your project does not get re-built, only re-linked. To avoid cross-compiling sources in this manner, use the $(GCBUILD) macro.

Instead of separating your .OBJ files into separate directories off the root \WGDEV directory, each project has a directory beneath it called GCBUILD. The GCBUILD directory has the following directories beneath it:

These directories contain all relevant compile time files (.OBJ, .DEF, .LIB...). Adding the $(GCBUILD) macro to the beginning of your project forces the following:

1. Checks the list of previous $(PARSEOPTS) saved in the GCBUILD directories. If they are identical, nothing else happens. This is to insure that all relevant files are re-parsed with the proper $(PARSEOPTS) macro.

If the GCBUILD directory does not exist, the following happens:

2. All files are parsed to the GCBUILD directory.

3. .GIF, .JPG, and .BIN files are copied to the appropriate directories.

The GCBUILD directories may be deleted at any time. They only contain files that are needed for compile time. Deleting the directory does not harm your project.

Projects will not compile properly if the $(GCBUILD) macro is left out. Inserting it insures that the projects are compiled the way you want them to be.

Creating .VIR files from within .MAK files.

You now have the ability to create .VIR files as part of your make procedures. Adding another dependency to your .MAK file forces .VIR files to be built on the fly. The following lines be added to accomplish this:

VIRFILES =                      \
        file1.vir                       \
        file2.vir                       \
        file3.vir

then adding $(VIRFILES) as one of your DLL dependencies forces the .VIR files to be built. You must have an equivalent .BCR file located in your project directory. The creation of .VIR files under the Windows NT/95 server environment is set up for you by default. However, if you wish to create .VIR files for DOS, you must own a copy of the utility BUTIL.EXE included with the Btrieve Developers Kit. If you own a copy of BUTIL.EXE, the environment variable BUDOS should be pointed to it. If BUDOS is in your environment .VIR files are created for DOS. Example:

set BUDOS=C:\BUTIL\BUTIL.EXE

Compilation Batch Files

Most compilation batch files have a matching debug batch file. The difference between the two is the debug version passes -DDEBUG to MAKE. Both mkntd galfil and mknt galfil -DDEBUG do the exact same thing. The following is a list of batch files used for the compilation of the Major BBS source:

MKNT.BAT and MKNTD.BAT

Applies to: WG3.x

Header check: the "BC5" named in this and the next two sections is the environment variable BC50 (as in "Environment Variables"). The batch files test only WGDEV and WGNT/WGDOS (WGDEV/BIN/MKNT.BAT, MKDOSL.BAT, MKDOSP.BAT); BC50 is read by the make files (SRC/bc50-32.mak:8-13).

Compiles Borland C files for Worldgroup NT/95. The environment variables WGNT, WGDEV, and BC5 are required for these batch files.

MKDOSL.BAT and MKDOSLD.BAT

Compiles Borland C files for Worldgroup DOS in LARGE mode. The environment variables WGDOS, WGDEV, and BC5 are required for these batch files.

MKDOSP.BAT and MKDOSPD.BAT

Compiles Borland C files for Worldgroup DOS in PHARLAP mode. The environment variables WGDOS, WGDEV, BC5, and DOSEXT are required for these batch files.

MK31V.BAT and MK31VD.BAT

Applies to: WG1-3.x (Client)

MK31V and MK31W build 16-bit Windows client DLLs.

Compiles 16 bit Borland C files for Windows. When these batch files are used, VB-Runtime errors replace the normal Galacticomm catastro functions. The environment variables WGMAN, WGDEV, and BC31 are required for these batch files.

MK31W.BAT and MK31VW.BAT

Applies to: WG3.x

Header check: the debug twin of MK31W.BAT is MK31WD.BAT; there is no MK31VW.BAT in the kit (WGDEV/BIN).

Compiles 16 bit Borland C files for Windows. When these batch files are used, catastros simply cause the windows DLL to terminate. The environment variables WGMAN, WGDEV, and BC31 are required for these batch files.

MKMVC.BAT

Compiles Microsoft Visual C++ 4.2 files from the command line using a wrapping .MAK file. Examples of this can be found in the \WGDEV\VCPROJ project directories. The environment variables WGNT, WGDEV, and MVC42 are required for this batch file.

MKVB.BAT and MKVBC.BAT

Applies to: WG1-3.x (Client)

MKVB/MKVBC build Visual Basic client programs.

Compiles Microsoft Visual Basic 3.0 files from the command line using a wrapping .MAK file. Examples of this can be found in the \WGMAN project directories. Both batch files require the WGDEV and VB3 environment variables. The MKVBC.BAT file requires the WGDOS and WGNT environment variables so that it can copy the client executables to their proper directories. For client builds, MKVBC.BAT requires that the .MDF file of the client you are building be located in your project directory.

MAKEWGS.BAT

The new usage for MAKEWGS.BAT is as follows:

MAKEWGS (What) (Type)
What Description
ALL Builds everything required for server.
SERVER Builds only server code.
SRVUTIL Builds only server utilities.
OFFLINE Builds all offline utilities.
DEVUTIL Builds all developer utilities.
API Builds all API relate libraries.
APP Builds all Major BBS Apps.
GALME Builds all messaging engine files.
CLIENT Builds all client files.
MVC Builds Microsoft Visual C++ apps.
JAVA Builds Java Apps.
Type Description
DOS Build Worldgroup for DOS.
DOSD Build Worldgroup for DOS, debug mode.
WNT Build Worldgroup for NT.
WNTD Build Worldgroup for NT, debug mode.

You can pass defines to MAKEWGS.BAT. Here is an example of compiling all Windows NT source with source debugging:

makewgs all wntd -DSRCDBG

Applies to: WG3.x

Header check: MAKEWGS.BAT takes the "What" argument as %1 and the "Type" as %2 (as printed). For ALL it sets COMPWHAT=!devutil !client !debug !lib and passes it to galmklst with BIN\makefile.lst, so what ALL really builds is decided by galmklst and makefile.lst, not by the batch file; the "Builds everything required for server" wording could not be confirmed from the kit (WGDEV/BIN/MAKEWGS.BAT).

New Development Utilites

For complete functionality of each new executable simply run the programs. Below is a list of all new programs added to the development environment.

GALCOPY.EXE

Generic utility used to copy files. Mainly created because of differences between the Windows 95 and Windows NT copy commands. It is used by GCRULES.MAK to copy files to proper directories.

GALMERGE.EXE

Message file merging utility. Used by GCRULES.MAK to merge your project .MSG files with existing .MSG files.

GALMKDIR.EXE

Generic mkdir program. It can take a nested directory path and create it without error. Used by GCRULES.MAK to make sure all directories needed are created before compile time.

GALPARSE.EXE

Utility used to parse all (.MSG, .MDF, .HTM...) files. This utility is used in conjunction with the $(PARSEOPTS) macro in .MAK files. All options that are passed on to the compiler in your .MAK files are passed on by adding to the $(PARSEOPTS) macro. This macro is used in conjunction with other internal defines to parse all needed files.

GALSYNC.EXE

Used by the $(GCBUILD) macro in your .MAK files to make sure that your project is being compiled with the same #defines. A complete description of how this works can be found in the section on the $(GCBUILD) macro.

GALPROD.EXE

Applies to: WG3.x

Editor's note: the list above is not complete. \WGDEV\BIN also contains GALPORT.EXE (source SRC\devutils\galport\GALPORT.C, named in the DEVUTILS entry of the source tree above), GALMKLST.EXE, GALPRLST.EXE, GALPARSF.EXE, CVTCHECK.EXE, REGSCAN.EXE and SCN2C.EXE. GALPORT is documented in chapter 28.

Timestamping utility similar to touch.exe. However, this utility allows you to touch a file with a new date as well as time.