TITLE=DOSLIB
ROUTE=/dos/doslib
LOCALE=en
MODIFIED=1792180394
URL=https://wiki.teletypegames.org/dos/doslib
L=1 #16
L=2 #18
L=3 #15
L=4 #49
L=5 https://git.teletypegames.org/dos/doslib


q│ DOSLIB is the code that the DOS programs 1DOSINST, 2GMENU, 3BMAGIC and 4TTGWIKI

q│ share (C++, Open Watcom, 16-bit DOS and Win32), and the rules their code

q│ follows. Each program has it in its 
cSOURCE/lib
q folder as a git subtree, so

q│ it builds on its own.

• 
bRepository:
0 5git.teletypegames.org/dos/doslib


1What is in it

1═════════════


t┌──────────────────────────────┬─────────────────────────────────────────────┐

t│
h Folder                       
t│
h What                                        
t│

t├──────────────────────────────┼─────────────────────────────────────────────┤

t│
0 
ccore
0                         
t│
0 No I/O: strings and 8.3 names, INI files,   
t│

t│
0                              
t│
0 UTF-8 and code page 437, the code pages 437 
t│

t│
0                              
t│
0 and 852 with one byte a character           
t│

t│
0                              
t│
0 (
ccode_page
0), CRC-32, the shared 
cError
0.      
t│

t├──────────────────────────────┼─────────────────────────────────────────────┤

t│
0 
cplatform
0                     
t│
0 The interfaces of the machine: 
cScreen
0,      
t│

t│
0                              
t│
0 
cKeyboard
0, 
cMouse
0, 
cClock
0, 
cFileSystem
0,         
t│

t│
0                              
t│
0 
cNetwork
0, ...                                
t│

t├──────────────────────────────┼─────────────────────────────────────────────┤

t│
0 
cplatform/dos
0, 
cplatform/win32
0 
t│
0 Their implementations: video memory, BIOS,  
t│

t│
0                              
t│
0 INT 33h, the Watcom C library; the Win32    
t│

t│
0                              
t│
0 console.                                    
t│

t├──────────────────────────────┼─────────────────────────────────────────────┤

t│
0 
cnet
0                          
t│
0 An FTP client on the 
cNetwork
0 interface.     
t│

t├──────────────────────────────┼─────────────────────────────────────────────┤

t│
0 
cui
0                           
t│
0 Drawing on a 
cScreen
0, the BIOS key codes, a  
t│

t│
0                              
t│
0 list cursor.                                
t│

t├──────────────────────────────┼─────────────────────────────────────────────┤

t│
0 
ctesting
0                      
t│
0 The hooks of the test builds (scripted      
t│

t│
0                              
t│
0 keys, screen dump), and test doubles for    
t│

t│
0                              
t│
0 the unit tests on the host.                 
t│

t├──────────────────────────────┼─────────────────────────────────────────────┤

t│
0 
ctools
0                        
t│
0 The Watcom build helper, the layer check,   
t│

t│
0                              
t│
0 the unit test runner, the formatter.        
t│

t└──────────────────────────────┴─────────────────────────────────────────────┘


1Layers

1══════

A program is built in layers; each uses only the ones below it, and only
through their interfaces:


p main_*.cpp     the machine: picks the platform implementations               

p app/           puts the layers together                                      

p controller/    keys and commands -> service calls                            

p view/          draws                                                         

p service/       what the program does                                         

p repository/    interfaces of the storage; repository/<kind>/ implements them 

p model/         the data and its rules, no I/O                                

p platform/      the program's own machine interfaces and their implementation»

p s                                                                            

p lib/           DOSLIB                                                        


ctools/check_layers.py
0 checks it in CI: which folder may include which, that
the DOS and Windows headers are only in the platform code, no 
cgoto
0, no 
cexit()
outside 
cmain
0. Everything above the platform also compiles on the host, so it
is unit tested there, without DOSBox.


1The code

1════════

• C++98, the part Open Watcom compiles: classes, pure virtual interfaces,
  references, simple templates; no exceptions, RTTI, STL or C++11.
• Interfaces are named by what they are (
cFileSystem
0), implementations by how
  (
cDosFileSystem
0, 
cFakeFileSystem
0). Dependencies come in through the
  constructor; only 
capp/
0 and 
cmain_*.cpp
0 create concrete objects.
• Failures are a 
cbool
0 and a shared 
cError
0; no global state outside the platform
  code.
• Files 
csnake_case
0, types 
cPascalCase
0, functions 
ccamelCase
0, members 
cname_
0;
  clang-format 18 with the repository's 
c.clang-format
0.


1Updating a program

1══════════════════


p git subtree pull --prefix=SOURCE/lib ssh://git@git.teletypegames.org:2222/do»

p s/doslib master --squash                                                     

A change made in a program's 
cSOURCE/lib
0 goes back with 
cgit subtree push

c--prefix=SOURCE/lib ... master
0.


1Open Watcom notes

1═════════════════

• The 16-bit compiler of the large model crashes on a module name longer than
  25 characters; the build cuts it with 
c-nm
0.
• A static object over 32 KB ends up in the EXE file: big objects are
  allocated on the heap.
• On 16 bits the layers cost size (far pointers, constructors, virtual
  tables): GMENU grew from 30 to 45 KB, DOSINST from 77 to 90 KB.