TITLE=BMAGIC
ROUTE=/dos/bmagic
LOCALE=en
MODIFIED=1792417593
URL=https://wiki.teletypegames.org/dos/bmagic
L=1 #17
L=2 #18
L=3 #16
L=4 https://git.teletypegames.org/dos/bmagic
L=5 https://git.teletypegames.org/dos/bmagic/releases/download/v0.1.0/BMAGIC-v0.1.0.zip
L=6 https://git.teletypegames.org/dos/bmagic/releases/download/v0.1.0/BMAGIC.EXE
L=7 https://git.teletypegames.org/dos/bmagic/releases
L=8 https://github.com/open-watcom/open-watcom-v2


q│ Boot Magic (
cBMAGIC.EXE
q) is a DOS program (C++, Open Watcom, 16-bit, about 64

q│ KB) that edits the boot menu of MS-DOS 6 and later. It reads 
cCONFIG.SYS
q,

q│ 
cAUTOEXEC.BAT
q and 
cMSDOS.SYS
q in the root folder of the boot drive, maps the

q│ menu in them, and lets you add, edit, copy, rename, move and delete menu

q│ items, edit their lines, and set the default item, the timeout, the colors

q│ and NumLock. It also sets the startup options of a Windows 95/98 
cMSDOS.SYS
q.

q│

q│ It changes only the lines it has to change. Before every save it shows the

q│ changes in a diff and backs up the files; any backup can be compared with

q│ the files on the disk or restored. It is built in layers on 1DOSLIB, like

q│ 2GMENU and 3DOSINST.

• 
bRepository:
0 4git.teletypegames.org/dos/bmagic
• 
bDownload v0.1.0:
0 5BMAGIC-v0.1.0.zip · the executable alone: 6BMAGIC.EXE
• 
bReleases:
0 7git.teletypegames.org/dos/bmagic/releases


i[Image: Boot Magic on a drive without a boot menu]


1Installation

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

• 
bWith DOSINST:
0 
cDOSINST INSTALL BMAGIC
0 installs the latest release from the
  3DOSINST store to 
cC:\APPS\BMAGIC
0, and running it again updates it. An update
  keeps the backups (DOSINST keeps files it did not install); 
cDOSINST REMOVE
  
cBMAGIC
0 deletes the folder, the backups too.
• 
bBy hand:
0 copy 
cBMAGIC.EXE
0 to any folder, for example 
cC:\APPS\BMAGIC\
0.


p BMAGIC        the boot files of the boot drive                               

p BMAGIC D:     the boot files of another drive (for example a disk you prepar»

p e)                                                                           

The boot drive comes from DOS (4.0 and later); if DOS cannot tell, Boot Magic
uses 
cC:
0. In DOSBox give the drive (
cBMAGIC C:
0), because DOSBox does not boot
from these files. The exit code is 0 when files were written, 1 when nothing
was written, and 2 on an error. Restart the computer after saving: DOS reads
these files only at boot.


1The boot menu

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


p CONFIG.SYS                          AUTOEXEC.BAT                             

p   [MENU]                              @ECHO OFF                              

p   MENUITEM=NORMAL,Normal start        PATH C:\DOS        <- every configurat»

p ion                                                                          

p   MENUITEM=GAMES,Games (EMS)          GOTO %CONFIG%                          

p   MENUDEFAULT=NORMAL,10               :NORMAL                                

p   MENUCOLOR=15,1                      LH SMARTDRV                            

p   NUMLOCK=OFF                         GOTO END                               

p                                       :GAMES                                 

p   [COMMON]                            LH MOUSE                               

p   DOS=HIGH,UMB      <- every item     GOTO END                               

p                                       :END                                   

p   [NORMAL]                                                                   

p   DEVICE=C:\DOS\HIMEM.SYS                                                    

p   [GAMES]                                                                    

p   DEVICE=C:\DOS\HIMEM.SYS                                                    

p   DEVICE=C:\DOS\EMM386.EXE RAM                                               

An item is a 
cMENUITEM
0 line of 
c[MENU]
0, a 
c[NAME]
0 block in 
cCONFIG.SYS
0, and a
section of 
cAUTOEXEC.BAT
0 from the 
c:NAME
0 label to the next label. DOS sets

cCONFIG
0 to the name of the chosen item, and 
cGOTO %CONFIG%
0 jumps to its label.
The sections end with a 
cGOTO
0 to a common end label (
c:END
0 unless the file uses
another one).


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

t│
h Action    
t│
h Key                   
t│
h What changes                           
t│

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

t│
0 New item  
t│
0 Ins                   
t│
0 A 
cMENUITEM
0 line after the last one, a  
t│

t│
0           
t│
0                       
t│
0 
c[NAME]
0 block after the last item       
t│

t│
0           
t│
0                       
t│
0 block, a section before the end label  
t│

t│
0           
t│
0                       
t│
0 ending with 
cGOTO END
0. It can be a copy 
t│

t│
0           
t│
0                       
t│
0 of another item. The first item of a   
t│

t│
0           
t│
0                       
t│
0 
cCONFIG.SYS
0 without a menu creates      
t│

t│
0           
t│
0                       
t│
0 
c[MENU]
0, and the lines already there go 
t│

t│
0           
t│
0                       
t│
0 under 
c[COMMON]
0.                        
t│

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

t│
0 Rename    
t│
0 F3                    
t│
0 The 
cMENUITEM
0 line, the 
c[NAME]
0 line,    
t│

t│
0           
t│
0                       
t│
0 
cMENUDEFAULT
0, the 
cINCLUDE=NAME
0 lines    
t│

t│
0           
t│
0                       
t│
0 and the 
c:NAME
0 label.                   
t│

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

t│
0 Delete    
t│
0 Del, then Y           
t│
0 The 
cMENUITEM
0 line, the block, the      
t│

t│
0           
t│
0                       
t│
0 section, 
cMENUDEFAULT
0 and the 
cINCLUDE
0   
t│

t│
0           
t│
0                       
t│
0 lines. Deleting the last item also     
t│

t│
0           
t│
0                       
t│
0 removes 
c[MENU]
0 and 
cGOTO %CONFIG%
0.      
t│

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

t│
0 Move      
t│
0 Ctrl+PgUp / Ctrl+PgDn 
t│
0 Swaps two 
cMENUITEM
0 lines, the order of 
t│

t│
0           
t│
0                       
t│
0 the menu.                              
t│

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

t│
0 Menu      
t│
0 F6, F5                
t│
0 
cMENUDEFAULT
0 (item and 0-90 s timeout), 
t│

t│
0           
t│
0                       
t│
0 
cMENUCOLOR
0, 
cNUMLOCK
0; F5 makes the       
t│

t│
0           
t│
0                       
t│
0 selected item the default.             
t│

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

t│
0 Lines     
t│
0 Enter, F8             
t│
0 The block and section of an item, or a 
t│

t│
0           
t│
0                       
t│
0 whole file (Tab moves to the next      
t│

t│
0           
t│
0                       
t│
0 one). Lines are edited up to 200       
t│

t│
0           
t│
0                       
t│
0 characters.                            
t│

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

t│
0 MSDOS.SYS 
t│
0 F7                    
t│
0 
cBootMenu
0, 
cBootMenuDefault
0,             
t│

t│
0           
t│
0                       
t│
0 
cBootMenuDelay
0, 
cBootGUI
0, 
cLogo
0, 
cBootKeys
0 
t│

t│
0           
t│
0                       
t│
0 in the 
c[Options]
0 block of a Windows    
t│

t│
0           
t│
0                       
t│
0 95/98 
cMSDOS.SYS
0; its attributes are    
t│

t│
0           
t│
0                       
t│
0 kept. The binary MS-DOS 6 
cMSDOS.SYS
0 is 
t│

t│
0           
t│
0                       
t│
0 not touched.                           
t│

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

A name is 1-8 letters, digits, 
c_
0 or 
c-
0, not 
cMENU
0 or 
cCOMMON
0. Batch labels count
only 8 characters, so the first 8 must differ from the other items'. An item
whose block or label is missing shows 
cnone
0 or 
cno label
0 in red: a missing label
stops 
cGOTO %CONFIG%
0. F1 shows all the keys.


1Saving and backups

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

Nothing is written until you save. F4 shows the changes so far, and F2 first
shows the same review: removed lines in red, added lines in green, with 3
unchanged lines around them. F2 in the review saves:

1. A new backup set goes to 
cBACKUP\NNN\
0 next to 
cBMAGIC.EXE
0: a byte-for-byte
   copy of each boot file and a 
cSET.INI
0 with the date, time, drive and a note.
   If the backup cannot be made, nothing is saved.
2. Each changed file is written as 
cX.$$$
0; the old file is renamed to 
cX.BM$
0,
   the new one takes its name, then 
cX.BM$
0 is deleted. If a step fails, the old
   file is put back. Line ends and the EOF byte stay as they were.
3. Files that had the read-only, hidden or system attribute get it back.

F9 lists the backups. Enter compares one with the files on the disk in the
same diff view, Ins makes a backup now, Del deletes one, and R restores one —
after first backing up the files it replaces.


1Building and tests

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

The build needs 8Open Watcom v2 (in 
c~/.local/opt/watcom
0, or 
cWATCOM=<folder>
0),
the same toolchain as the other DOS programs:


p SOURCE/build.sh                      # ../BMAGIC.EXE                         

p SOURCE/build.sh test                 # the test version (keys from TESTKEYS.»

p TXT)                                                                         

p SOURCE/test/unit/run.sh              # unit tests on the host, layer check f»

p irst                                                                         

p python3 SOURCE/test/run.py           # screen tests in DOSBox, on sample boo»

p t drives                                                                     

The layers follow the 1DOSLIB rules: 
cmodel
0 (the menu map, the editor, the diff,
no I/O), 
crepository
0 (the boot files and the backup sets), 
cservice
0, 
ccontroller
0,

cview
0, 
cplatform
0 (the boot drive, attributes, the clock) and 
capp
0; DOSLIB is a
git subtree in 
cSOURCE/lib
0.

Woodpecker runs the style check, the layer check and the unit tests, then the
build and the DOSBox tests on every push. A 
cvX.Y.Z
0 tag, matching 
cVersion
0 in

cSOURCE/app/version.h
0, publishes a Gitea release and puts 
cBMAGIC
0 into the
DOSINST store. The test step runs in the 
cdos-ci
0 image of the Gitea registry
(
cgit.teletypegames.org/build/dos-ci:bookworm
0), which has the toolchain
preinstalled: 
cscripts/ci-toolchain.sh
0 installs only when the image's versions
differ from its pins. The screen tests run four cases at a time (
cJOBS
0, each in
its own folder). The release step runs in the 
cci-tools
0 image with nothing to
install. The store step sends the folder as a tar over SSH to the server's

cdeploy
0 user (
cdeploy-ssh
0 image, referenced by digest), whose key is bound to
one fixed command, 
cci-deploy
0 (
cinfra/host-config
0); the pipeline needs no
trusted volumes.


1Limitations

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

• At most 9 menu items, as DOS shows them. Further 
cMENUITEM
0 lines and 
cSUBMENU
  lines are kept but not shown; the file editor (F8) reaches them.
• Only the 
cGOTO %CONFIG%
0 style of 
cAUTOEXEC.BAT
0 is mapped. 
cIF
  
c"%CONFIG%"=="GAMES" ...
0 lines are kept, but a rename does not change them.
• A file of at most 16000 bytes and 500 lines.
• The diff looks at most 50 lines ahead for where the files agree again;
  larger moves show as removed and added lines.