npm package: @rawrs/borland-c-2
Description: A browser-supported library that can run various tools from Borland C 2.0, a C++ compiler from 1991.
Author: wilkie
Latest version: 1.0.7

# Borland C 2.0 WebAssembly

This is a emulation wrapper around the Borland C 2.0 compiler toolchain from
1991.

This compiler was distributed by Borland for free within their archival
initiative. It is meant for the archival and historic purposes of maintaining
older C code from the DOS era.

## Credits

This project makes use of a modified build of [DOSBox](https://www.dosbox.com/),
which is licensed under the GPLv2 and available at [@rawrs/dosbox](https://gitlab.com/rawrs/dosbox.js).

## Usage via NPX

You can directly call upon the compiler (BCC) via this package: (see
`examples/MAIN.CPP` for a C file to test with)

```shell
npx @rawrs/borland-c-2 MAIN.CPP
```

This creates `MAIN.EXE` and the intermediate file `MAIN.OBJ`.

To print out the BCC usage, just run it without any arguments at all:

```shell
npx @rawrs/borland-c-2

Borland C++  Version 2.0 Copyright (c) 1991 Borland International
Syntax is: BCC [ options ] file[s]     * = default; -x- = turn switch x off
  -1      80186/286 Instructions    -2      80286 Protected Mode Inst.
  -Ax     Disable extensions        -B      Compile via assembly
  -C      Allow nested comments     -Dxxx   Define macro
  -Exxx   Alternate Assembler name  -G      Generate for speed
  -Hxxx   Use pre-compiled headers  -Ixxx   Include files directory
  -K      Default char is unsigned  -Lxxx   Libraries directory
  -M      Generate link map         -N      Check stack overflow
  -O      Optimize jumps            -P      Force C++ compile
  -Qxxx   Memory usage control      -S      Produce assembly output
  -Txxx   Set assembler option      -Uxxx   Undefine macro
  -Vx     Virtual table control     -Wxxx   Create Windows application
  -X      Suppress autodep. output  -Yx     Overlay control
  -Z      Optimize register usage   -a      Generate word alignment
  -b    * Treat enums as integers   -c      Compile only
  -d      Merge duplicate strings   -exxx   Executable file name
  -fxx    Floating point options    -gN     Stop after N warnings
  -iN     Max. identifier length    -jN     Stop after N errors
  -k      Standard stack frame      -lx     Set linker option
  -mx     Set Memory Model          -nxxx   Output file directory
  -oxxx   Object file name          -p      Pascal calls
  -r    * Register variables        -u    * Underscores on externs
  -v      Source level debugging    -wxxx   Warning control
```

Just specifying a set of "CPP" or "C" files will use the default options
for the compiler followed by the file listing, which is roughly equivalent to:

```
BCC -ms -p- -k -V -Z -O -r -G -ID:\\BC2\\INCLUDE -LD:\\BC2\\LIB MAIN.CPP
```

You can specify all of these options just by including them, and it will
automatically use the `-I` and `-L` to point to the internal paths for the
standard includes and libraries:

```shell
npx @rawrs/borland-c-2 -ms -p- -k -V -Z -O -r -G MAIN.CPP
```

If you want to completely use your own and omit these, specify
`--no-system-includes` and/or `--no-system-libs`

You can build a `CPP` file and not link it via `-S` for just assembly:

```shell
npx @rawrs/borland-c-2 -ms -p- -k -V -Z -O -r -G -S MAIN.CPP
```

which creates `MAIN.ASM`. If you want just the object file, use `-c`:

```shell
npx @rawrs/borland-c-2 -ms -p- -k -V -Z -O -r -G -c MAIN.CPP
```

Which creates an `OBJ` file with the same name as the `CPP`.

Then to link that `MAIN.OBJ` file to create an executable, use `TLINK`.
Run it alone to see the options:

```shell
npx -p @rawrs/borland-c-2 tlink

Turbo Link  Version 4.0 Copyright (c) 1991 Borland International
Syntax: TLINK objfiles, exefile, mapfile, libfiles, deffile
@xxxx indicates use response file xxxx
Options: /m = map file with publics
         /x = no map file at all
         /i = initialize all segments
         /l = include source line numbers
         /L = specify library search paths
         /s = detailed map of segments
         /n = no default libraries
         /d = warn if duplicate symbols in libraries
         /c = lower case significant in symbols
         /3 = enable 32-bit processing
         /v = include full symbolic debug information
         /e = ignore Extended Dictionary
         /t = create COM file (same as /Tc)
         /o = overlay switch
         /P[=NNNNN] = pack code segments
         /A=NNNN = set NewExe segment alignment factor
         /ye = expanded memory swapping
         /yx = extended memory swapping
         /C  = case sensitive exports and imports
         /Txx = specify output file type
               /Tdx = DOS image (default)
               /Twx = Windows image
                (third letter can be c=COM, e=EXE, d=DLL)
```

For a simple case, where we used the small memory model (`-ms`) when compiling,
we can link our `MAIN.OBJ` to both the C runtime for small ("S") memory (`C0S.OBJ`)
and the C standard library (`CS.LIB`) via:

```shell
npx -p @rawrs/borland-c-2 tlink C0S MAIN.OBJ,MAIN.EXE,,CS
```

To link more objects, specify them together... and to link more libraries
do the same for them at the end:

```shell
npx -p @rawrs/borland-c-2 tlink C0S MAIN.OBJ ANOTHER.OBJ,MAIN.EXE,,CS MATHS
```

You can also directly invoke the assembler, `TASM`, via:

```shell
npx -p @rawrs/borland-c-2 tasm
```