Development Environment (Worldgroup 3.x)
Applies to: v10
This chapter describes the Worldgroup 3.x tool chain (Borland C++ 5.00,
\WGDEV,.MAKfiles,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.MAKmacros,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",BC5forBC50, 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 sameBC50variable (WGDEV/SRC/bc551-32.mak:4-13), alongsidebc50-32.mak,bc45.makandbc31.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
VB3variable,MK31V/MK31W,MKVBbelow) 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
VB3variable (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:
ICSRCis where the Active HTML kernel lives (icsrc\galacth, headerGALACTH.H) and the Active HTML ("ah") applications are inAPPS(galfilah,galpnqah,galregah); see the Active HTML note under "Files contained in each project". The kit has three more top-levelSRCdirectories than the addendum lists:experimental,faxsrcandinsutils;UTILS,OFFLINE,REBUILDandWGSERVERsit underSERVER, 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\WGTOOLSdirectory (THEDRAW.*,WGSSYNC,BTRIEVE). Command-line tools are in\WGDEV\BIN; keep that entry on thePATH.
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,.GIFand.JPGfiles 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 headersGALACTH.H,DNF.HandDNFMGR.Hare 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.txtsection 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.His still ininc/, 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:
srcin the!includeline,LARGE, and the three added linesstart: \,$(GCBUILD) \andtticwd.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)
HTMLDIRandGIFDIRare Active HTML macros.
Applies to: v10
Not in v10. Active HTML is not supported in v10 (
MBBS10.txtsection 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.His still ininc/, 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\imagesinGCRULES.MAK:103; "webages" above is a typo in the addendum.CVTFILDIR,HTMLDIRandGIFDIRare all defined inGCRULES.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:
- WNT - Windows NT compilation files.
- WNTD - Windows NT debug compilation files.
- DOSP - DOS Pharlap compilation files.
- DOSPD - DOS Pharlap debug compilation files.
- DOSL - DOS large compilation files.
- DOSLD - DOS large debug compilation files.
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.EXECompilation 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 onlyWGDEVandWGNT/WGDOS(WGDEV/BIN/MKNT.BAT,MKDOSL.BAT,MKDOSP.BAT);BC50is 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)
MK31VandMK31Wbuild 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.BATisMK31WD.BAT; there is noMK31VW.BATin 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/MKVBCbuild 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.BATtakes the "What" argument as%1and the "Type" as%2(as printed). ForALLit setsCOMPWHAT=!devutil !client !debug !liband passes it togalmklstwithBIN\makefile.lst, so whatALLreally builds is decided bygalmklstandmakefile.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\BINalso containsGALPORT.EXE(sourceSRC\devutils\galport\GALPORT.C, named in theDEVUTILSentry of the source tree above),GALMKLST.EXE,GALPRLST.EXE,GALPARSF.EXE,CVTCHECK.EXE,REGSCAN.EXEandSCN2C.EXE.GALPORTis 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.