DJGPP cross-compiler with POSIX threads Files

#
# This distribution is a modified version of DJGPP v2.05
# The official/original DJGPP can be found at https://delorie.com/djgpp/
# 

Build script for a DJGPP cross-compiler with POSIX threads (and std::thread)
Copyright (C) 2025 by Alexander Bruines <alexander.bruines@gmail.com>

This entire distribution, including any scripts and patches used to build it,
are distributed under the terms described in the file COPYING.DJ.

COPYING.DJ should be in the same directory as this file but can also be found
at: https://www.delorie.com/djgpp/dl/ofc/simtel/v2/copying.dj


Introduction:
-------------

These scripts and patches attempt to build a Debian GNU/Linux to DJGPP/DOS
cross-compiler with POSIX threads and working std::thread.

This is the README file for the modifications I've made to DJGPP v2.05 and
GNU BINUTILS, GCC and Portable Thread Library.

If you are reading this file then you already have the build scripts used
to build this GNU/Linux to DOS cross-compiler. The scripts are located at:

	/usr/local/i586-pc-msdosdjgpp/src/

NOTICE: All applications produced with this unofficial DJGPP release must
        (if distributed) comply with the GNU General Public License version 2.


POSIX threads support:
----------------------

Basically this build has been 'fixed' so that both the DJ???205.ZIP packages and
GNU Portable Thread library (PTH207S.ZIP in the V2GNU directory of the DJGPP
distribution) build cleanly with a 'modern' GCC and should work as expected.

Also GCC is modified to use the pthread library and I've added the -pthread
command-line option to GCC for use with DJGPP. This option defines the _REENTRANT
macro and enables automatic linking with the GNU Portable Thread (and external
sockets) library.

After applying the modifications GCC sort of automagically picked it up from
there and enabled std::thread (and friends) in C++.

To actually get std::thread running (and not just compiling) more modifications
are needed. Specifically changes to CRT0 and CRT1 sources of the DJGPP runtime
and some fixups in GCC are required for this.


Watt32 Sockets library:
-----------------------

Compiling the pthread library requires a sockets implementation.
I have only made sure that this code builds cleanly and can be integrated
into this build of DJGPP.

This means that I have not tested any of the functionality this library
provides. If you want a DJGPP that includes this library see the HAVE_WATT32
variable in djgpp-builder.cfg. 


PthSock library (dummy sockets library):
----------------------------------------

This is a sockets library that I've written just to provide the minimum
required for building the GNU Portable Thread library without needing Watt32.
It does not provide any actual functionality.

I prefer this since I have no need for a sockets library (yet).
The source code is included in the djgpp-builder.tar file.


Building the DJGPP cross-compiler:
----------------------------------

The scripts used to build this version of DJGPP are actually three makefiles.
The files are:

	djgpp-builder
	djgpp-builder.mak
	djgpp-builder.cfg

They are meant to be used on Debian GNU/Linux but could be made to work with
Debian based distributions.

The 'djgpp-builder' file has been made executable and has an approriate she-bang
(that runs make) so it can be run directly from a shell.

When executed without any argument it will list all the available options.
For (just) building the cross-compiler it should be enough to:

 - Place the scripts in a directory with at least 16GB of free space available.
 
 - Run (in order):
 
	sudo ./djgpp-builder apt

	./djgpp-builder build

	sudo ./djgpp-builder install


The first command installs the Debian packages needed to build DJGPP with these
scripts (debootstrap, build-essential, ...)

Running the script with the 'build' argument will:

 - Download all required source packages from DJGPP and GNU mirrors.
 - Create a 16GB imagefile.
 - Bootstrap a clean Debian 'chroot' onto the imagefile.
 - Install development packages in the chroot.
 - Copy all other required files into the chroot.
 - Build DJGPP in the chroot. (This may take several cups of COFFee.)
 - Create a zip file that can be extracted to the / directory to install DJGPP.

Before running the script you should review the 'djgpp-builder.cfg' file and
adjust the values defined there to your requirements.

After installation using the 'install' option of the build script GCC should
report something like:

$ i586-pc-msdosdjgpp-gcc -v
Using built-in specs.
COLLECT_GCC=i586-pc-msdosdjgpp-gcc
COLLECT_LTO_WRAPPER=/usr/local/libexec/gcc/i586-pc-msdosdjgpp/15.1.0/lto-wrapper
Target: i586-pc-msdosdjgpp
Configured with: ../configure --target=i586-pc-msdosdjgpp --prefix=/usr/local
 --enable-languages=c,c++,objc,obj-c++,fortran --with-tune=pentium
 --with-pkgversion='DJGPP 2.05' --enable-libquadmath-support
 --enable-libstdcxx-filesystem-ts --enable-lto --disable-libstdcxx-pch
Thread model: posix
Supported LTO compression algorithms: zlib zstd
gcc version 15.1.0 (DJGPP 2.05) 


Building Multi Threaded DJGPP applications:
-------------------------------------------

In your code you may use pthread library functions or C++ functionality
like std::thread, std::mutex, std::condition_variable, ... like usual.

I've tried many of the examples provided by cppreference.com and they work as
expected. The only thing not working (so far) is std::recursive_mutex but I
suspect that its not very useful with Cooperative Multi Threading anyway. 

To enable POSIX threads simply specify -pthread as one of the command-line
arguments passed to GCC. This applies to both compiling and linking.

Passing the -pthread option to GCC causes it to define the _REENTRANT macro
which is used by the system header files to detect if POSIX threads are enabled.

Specifying the -pthread option during linking will cause the pthread and sockets
libraries to be automatically included.

The Autoconf 'AX_PTHREAD' macro should work with DJGPP based projects that use
pthreads and is available at:

	http://www.gnu.org/software/autoconf-archive/ax_pthread.html

There are a couple of caveats that apply to the GNU Portable Threads library.

The most important one is that it implements Cooperative Multi Threading
meaning that all thread switching is explicit and done in software using long
jumps at specific points in your code (ie. where you call a pthread or MT-aware
function).

Also the state of the FPU is not saved/restored when switching threads.

One more thing to note is that the pthread.h header file uses macros to redirect
some libc/libsocket calls to pthread aware versions of those functions.

These macros prepend the text '__pthread_' to function calls like fork(),
sleep(), connect(), select() and others.

The above also means that if you use any of those names in your pthread enabled
code they will also be prepended with '__pthread_'. This is not a real problem
but may cause some confusion when debugging, or an actual issue when mixing code
compiled with and without specifying the -pthread option to GCC or when a source
file somehow doesn't include pthread.h and can't find a function that had its
name modified in this manner.


Modifications and patches:
--------------------------

This is just a short description of the most important modifications made to
each package. To see all modification please examine the build scripts and
individual patch files.

 - binutils : Modified the section alignment for the coff-go32 and coff-go32-exe
              file formats from 16 to 64 bytes.

 - gcc      : Apply patches made by comparing the official DJGPP released GCC
              (14.2.0) sources with the original GCC sources.

            : Change the maximum alignas() value from 16 to 64 bytes.

            : Fix-ups to get POSIX threads to compile/work.

            : Add the -pthread option for DJGPP.

 - DJ???205 : Modify crt0/crt1 for using std::thread and friends.

            : Fix-ups for building GCC with POSIX threads enabled.

 - Watt32   : Patch the header files for inclusion in DJGPP include directory.

            : Fix-ups for compilation issues.

 - PTh207s  : Fix-ups for compilation issues.