Skip to content

Commit 0ceb3ea

Browse files
LethjaLethja
committed
Moved build instructions to its own Markdown file BUILD.md.
1 parent 91676db commit 0ceb3ea

File tree

2 files changed

+209
-36
lines changed

2 files changed

+209
-36
lines changed

‎BUILD.md‎

Lines changed: 207 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,207 @@
1+
# Build System Requirements
2+
3+
## Mandatory
4+
To build Lua with Open Watcom you will need the following software and hardware in your development environment.
5+
6+
### Lua
7+
The Lua source code is not included directly in this repository and needs to be required.
8+
9+
#### Git Submodule
10+
Assuming the development environment has access to Git and the Internet,
11+
the easiest way to get the Lua source code is to initialize the submodule
12+
with `git submodules init` then `git submodules update --recursive`.
13+
14+
#### Website archive
15+
If Git is not available in the development environment,
16+
then Lua sources can be acquired from https://lua.org/ftp.
17+
Download any 5.4 version of the tarball sources and extract them.
18+
Then copy the contents inside the extracted `src` folder
19+
into the projects `lua` folder.
20+
21+
### Open Watcom
22+
23+
While Open Watcoms requirements are not difficult to satisfy, it
24+
should be noted that a DOS and/or x86 [emulator](README.md#emulators) might
25+
be required in some modern development environments,
26+
such as those not natively running on a x86(_64) processor.
27+
28+
#### Hardware
29+
Open Watcom requires a processor that is 80386 instruction
30+
set architecture compliant.
31+
32+
#### Operating System
33+
Open Watcom is available for several operating systems
34+
including DOS, OS/2, Windows and Linux.
35+
Regardless of which version is used, they are all capable of cross-compiling
36+
to other systems assuming a full installation was done.
37+
38+
> The DOS version of Open Watcom must be run on an operating system
39+
that supports the DOS4GW memory extender.
40+
If in doubt, consider [FreeDOS](https://www.freedos.org/download/)
41+
or [SvarDOS](http://svardos.org/).
42+
43+
## Optional
44+
These tools are not strictly needed to build Lua with Open Watcom
45+
but are beneficial.
46+
47+
### Patching Utility
48+
There are a few patches for the Lua source code available,
49+
however, the patch changes are minimal
50+
and only serve to silence Watcom compiler warnings.
51+
52+
#### GNU Patch
53+
The standard patch utility on GNU systems.
54+
It's likely already installed if the development environment is GNU/Linux,
55+
otherwise find it at https://savannah.gnu.org/projects/patch/.
56+
57+
#### DifPat
58+
An alternative to GNUs patching utility,
59+
DifPat stands out in that it can run on DOS systems
60+
and is included in the repositories
61+
of [FreeDOS](https://www.freedos.org/download/)
62+
and [SvarDOS](http://svardos.org/).
63+
It's also available at https://github.com/deverac/difpat.
64+
65+
### Ultimate Packer for eXecutables
66+
Ultimate Packer for eXecutables (UPX) can be used to compress the built binaries
67+
and save disk space on the end users machine.
68+
UPX is free software and is available in the repositories
69+
of [FreeDOS](https://www.freedos.org/download/), [SvarDOS](http://svardos.org/)
70+
and most Linux distributions as well as directly from https://upx.github.io/.
71+
72+
### GNU mtools
73+
mtools is a set of unix utility functions that allow handling of floppy disks
74+
on UNIX-like systems without mounting the disk. Although its default behaviour
75+
is to interact with real floppy disks and drives it is also possible to create
76+
and interact with disk image files (.IMA) using the `-i` option.
77+
78+
### Lua 5.4
79+
Some of the included scripts in the Lua for Watcom repository can be used to
80+
ensure repeatable builds are possible.
81+
To use these scripts, a Lua 5.4 compatible should be installed
82+
to the development environment. This may include the one being built.
83+
84+
# Building
85+
## Patch the source code for Open Watcom (optional):
86+
87+
Depending on which patching utility is installed, run the applicable command:
88+
89+
| GNU Patch | DifPat |
90+
|------------------------|-----------------|
91+
| `patch -p0 -i lua.pat` | `pat lua.pat .` |
92+
93+
## Setup Open Watcom build environment
94+
Open Watcom should contain a script for the respective development environment
95+
it was installed on named `OWSETENV` or similar.
96+
Running this script should set the correct environment in the
97+
shell it was run on. After running the script make sure that `WATCOM` is defined
98+
and points to a real directory by using the `echo` command to print it.
99+
Depending on your development environments operating system family,
100+
the command to do this may differ:
101+
### DOS/NT
102+
```bat
103+
echo %WATCOM%
104+
```
105+
### UNIX
106+
```sh
107+
echo $WATCOM
108+
```
109+
110+
## Build Lua with Open Watcom:
111+
112+
Run any of commands in the table below for the targets that should be built
113+
and be mindful of how the `INCLUDE` environment variable changes
114+
between different targets and development environments.
115+
116+
| INCLUDE (DOS/NT) | INCLUDE (UNIX) | Make Command | Binary File | Target OS | Target ISA |
117+
|-----------------------------|---------------------------|-------------------------|----------------------|-------------|------------|
118+
| `%WATCOM%\h` | `$WATCOM/h` | `wmake -f wm_dos16.mak` | `dist/bin/LUA16.EXE` | PC-DOS 2.0+ | 8086+ |
119+
| `%WATCOM%\h` | `$WATCOM/h` | `wmake -f wm_dos4g.mak` | `dist/bin/LUA4G.EXE` | MS-DOS 5.0+ | 80386+ |
120+
| `%WATCOM%\h;%WATCOM%\h\os2` | `$WATCOM/h:$WATCOM/h/os2` | `wmake -f wm_os216.mak` | `dist/bin/LUA21.EXE` | OS/2 1.2 | 80286+ |
121+
| `%WATCOM%\h;%WATCOM%\h\os2` | `$WATCOM/h:$WATCOM/h/os2` | `wmake -f wm_os232.mak` | `dist/bin/LUA22.EXE` | OS/2 2.0 | 80386+ |
122+
| `%WATCOM%\h;%WATCOM%\h\nt` | `$WATCOM/h:$WATCOM/h/nt` | `wmake -f wm_winnt.mak` | `dist/bin/LUANT.EXE` | Windows 95+ | 80386+ |
123+
124+
## Copy DOS4GW (optional)
125+
`LUA4G.EXE` requires `DOS4GW.EXE` to be accessible to it to run.
126+
The easiest way to ensure this is to copy the existing `DOS4GW.EXE` from the
127+
Open Watcom installation into the same directory.
128+
Depending on your development environments operating system family,
129+
the command to do this may differ:
130+
### DOS/NT
131+
```bat
132+
copy %WATCOM%/binw/dos4gw.exe dist/bin/DOS4GW.EXE
133+
```
134+
### UNIX
135+
```sh
136+
cp $WATCOM/binw/dos4gw.exe dist/bin/DOS4GW.EXE
137+
```
138+
139+
## Replicable builds of LUANT.EXE with PE95TIME.LUA (optional)
140+
`LUANT.EXE` is the Windows 95 version of the Lua for Watcom build.
141+
While the build is ready to run as it is, Open Watcom built the binary
142+
with timestamp metadata in the PE executable headers,
143+
meaning that subsequent builds will not be identical
144+
even if the executed code is the same.
145+
To fix this the `PE95TIME.LUA` script can be used
146+
to set this metadata time to August 21st 1995 (The release date of Windows 95).
147+
```sh
148+
lua PE95TIME.LUA dist/bin/LUANT.EXE
149+
```
150+
With this constant applied to the binary,
151+
it should now be identical to any other build with the same input.
152+
If it isn't, then tools like [diffoscope](https://diffoscope.org/)
153+
can be used to audit the difference
154+
without timestamps appearing as false positives.
155+
156+
## Compress binaries with UPX (optional)
157+
It's possible to compress some of the binaries so they take less disk space.
158+
```sh
159+
upx -9 --8086 dist/bin/LUA16.EXE dist/bin/LUA4G.EXE dist/bin/LUANT.EXE
160+
```
161+
OS/2 and DOS4GW binaries should NOT be compressed by UPX.
162+
163+
## Creating a floppy disk image with mtools (optional)
164+
The most convenient way to get Lua to some old hardware or an emulator might be
165+
to create a floppy disk image. This can be achieved with GNU mtools.
166+
167+
### Create disk image
168+
To create a disk use the `mformat` command
169+
with parameters best suited to the disk type for that machine.
170+
The most important parameters are:
171+
- `-C` Create if doesn't exist
172+
- `-i` Specify an image file path
173+
- `-v` Specify disk label
174+
- `-f` The size of the disk in kilobytes
175+
- `-N` Serial number of the disk
176+
177+
Example:
178+
```sh
179+
mformat -C -i Lua.ima -v "LUA" -f 1440 -N 12345
180+
```
181+
182+
### Copy files to disk image
183+
184+
With the disk image made copy over any files with `mcopy`.
185+
The most important parameters are:
186+
- `-m` Keep the old modification date of each file from the development system
187+
- `-i` Specify an image file path (which should be the same as was used in `mformat`)
188+
- `::` Specifies a path in the disk image
189+
190+
Example:
191+
```sh
192+
mcopy -m -i Lua.ima dist/bin/LUA16.EXE dist/bin/LUA4G.EXE dist/bin/LUANT.EXE dist/bin/DOS4GW.EXE ::
193+
```
194+
195+
## Trim the floppy disk image (optional)
196+
Because mtools is designed to work on real floppy drives as well as images
197+
`mcopy` may leave some junk data behind
198+
in unallocated sectors of the disks partition.
199+
Under normal circumstances this is uneventful,
200+
but when trying to create a replicable floppy disk image,
201+
this may cause the files to differ between builds.
202+
To fix this the `FATSTAT.LUA` script can be used with it's `-z` parameter
203+
to zero out any unused sector on the disk. This is sometimes called trimming
204+
or shredding by other tools.
205+
```sh
206+
lua FATSTAT.LUA -z Lua.ima
207+
```

‎README.md‎

Lines changed: 2 additions & 36 deletions
Original file line numberDiff line numberDiff line change
@@ -78,42 +78,8 @@ the OS is newer and has higher minimum requirements.
7878
| Windows Vista - 10 | 80686<br/>x86_64 | No | No | No | No | Yes |
7979
| Windows 11 | x86_64 | No | No | No | No | Yes |
8080

81-
## Build System Requirements
82-
To build Lua with Open Watcom you will need the following:
83-
84-
| Build Requirement | Sources |
85-
|---------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|
86-
| Lua 5.4 source code (or `git submodules`) | [lua.org](https://lua.org/ftp/) ([GitHub](https://github.com/lua/lua/tree/v5.4.7)) |
87-
| Open Watcom 1.9 (or later) | [openwatcom.org](https://www.openwatcom.org/) |
88-
| Operating System supported by Open Watcom<br/>(at least MS-DOS 5.0) | [FreeDOS](https://www.freedos.org/download/), [SvarDOS](http://svardos.org/) and/or an [emulator](#emulators) |
89-
| [80386 compatible processor](https://en.wikipedia.org/wiki/I386) | AMD/Intel processor made after 2008 or an [emulator](#emulators) |
90-
| A patching utility | [GNU Patch](https://savannah.gnu.org/projects/patch/) or [DifPat](https://github.com/deverac/difpat) |
91-
92-
> If in doubt, an [emulator](#emulators) can be used
93-
to run the DOS version of Open Watcom on a modern machine
94-
95-
## How to build
96-
1) Extract Luas source code to the `Lua` folder. This can be achieved in two ways:
97-
* Use `git submodules init` then `git submodules update --recursive` to get the sources directly from the Lua mirror repository
98-
* Download the Lua 5.4.x sources tarballs from https://lua.org/ftp/, extract them and copy all files in `src` to `Lua`
99-
2) Patch the source code for Watcom (optional):
100-
101-
| GNU Patch | DifPat |
102-
|------------------------|-----------------|
103-
| `patch -p0 -i lua.pat` | `pat lua.pat .` |
104-
> If no patching program is available mimic the changes in each `.pat` file manually.
105-
> Patch changes are minimal and only serve to silence Watcom compiler warnings
106-
107-
3) Build Lua with the following commands:
108-
109-
| Make Command | Binary File | Target OS | Target ISA |
110-
|-------------------------|----------------------|-------------|----------------|
111-
| `wmake -f wm_dos16.mak` | `dist/bin/lua16.exe` | PC-DOS 2.0+ | 8086 or later |
112-
| `wmake -f wm_dos4g.mak` | `dist/bin/lua4g.exe` | MS-DOS 5.0+ | 80386 or later |
113-
| `wmake -f wm_os216.mak` | `dist/bin/lua21.exe` | OS/2 1.2 | 80286 or later |
114-
| `wmake -f wm_os232.mak` | `dist/bin/lua22.exe` | OS/2 2.0 | 80386 or later |
115-
| `wmake -f wm_winnt.mak` | `dist/bin/luant.exe` | Windows 95+ | 80386 or later |
116-
81+
## Build
82+
See the [Build documentation](BUILD.md)
11783

11884
# See also
11985

0 commit comments

Comments
 (0)