Computing: Free Pascal Programming

Installing the Free Pascal DOS cross-compiler on Linux.

In my tutorial Installing Free Pascal on FreeDOS, I described how to install and use the Free Pascal for go32v2 on FreeDOS. I guess, it's this 32bit compiler, that a large majority of people, who write applications for DOS using Free Pascal, actually use. However, there is a 16bit DOS compiler (real mode, i8086 target) available; its advantages over FPC for GO32V2 and over Turbo Pascal, as well as its limitations, are described on the DOS page of the Lazarus wiki. Available, but not natively available. There isn't actually a 16bit Free Pascal compiler, that you can run on DOS. The only versions available are cross-compilers for Windows 32bit and for Linux 32bit and 64bit. For those, who don't know this expression: a cross-compiler is a compiler running on a given platform and creating executables for another platform (called the target platform). This tutorial describes how to install and use the Linux 64bit cross-compiler for DOS (compiler running on Linux and creating i8086 executables) on Linux Mint 20.3 64bit Cinnamon. The version of the compiler, that I use, is fpc 3.2.2 The procedure to follow should be similar for other Linux systems and other versions of FPC.

You can download the needed files from the Free Pascal i8086 MS-DOS download page. In fact, you need two files: the native compiler for the platform, where you want to do the compilation (in my case fpc-3.2.2.x86_64-linux.tar), and the cross-compiler for DOS (in my case fpc-3.2.2.x86_64-linux.cross.i8086-msdos.tar.xz). One of the questions, you may ask, is if you can install these files side by side with a Lazarus installation. I suppose that it's possible, as I suppose that this might cause problems of overwriting configuration files, if you don't take particularly care. This tutorial assumes, that Lazarus is not installed on your Linux Mint machine.

Installing the native compiler.

Copy the downloaded archive (fpc-3.2.2.x86_64-linux.tar) in some subfolder of your home directory (I created a new folder called "Software") and double-click it. The Linux Mint Archive Manager application opens, showing the archive content: a folder with the same name as the archive; extract it. The folder contains several files, among them an install script, that you can run in a terminal; cd to the fpc-3.2.2.x86_64-linux directory, and enter the following:     sudo ./install.sh

Installing the DOS cross-compiler.

Copy the downloaded archive (fpc-3.2.2.x86_64-linux.cross.i8086-msdos.tar.xz) in some subfolder of your home directory (I used "Software" as before) and extract it using the Archive Manager application: A folder with the same name as the archive is created; it contains two subfolders, respectively called bin and lib. bin contains a single file, a symbolic link to the cross-compiler, lib contains the folder structure fpc/3.2.2 with the cross-compiler executable (called ppcross8086) and two folders called fpmkinst and units. Both of these folders contain a subdirectory called msdos, containing the files that are necessary to create 16bit DOS executables.

The content of the fpc-3.2.2.x86_64-linux.cross.i8086-msdos folder may directly be copied to the filesystem below /usr). You may do this in File Explorer run as super-user: Copy the ppcross8086 symbolic link to /usr/bin Copy the ppcross8086 executable link to /usr/lib/fpc/3.2.2 Copy the folder fpmkinst/msdos to /usr/lib/fpc/3.2.2/fpmkinst Copy the folder units/msdos to /usr/lib/fpc/3.2.2/units

You may wonder if you can simply copy the symbolic link from the archive folder to /usr/bin. Doesn't this break the link to the executable, it should point to? No, it doesn't. In fact, if you have a look at the symbolic link's properties, you'll see that the target is expressed as a relative path starting with "../lib/fpc/3.2.2". So, the symlink being located in /usr/bin, it will point to a file in the directory /usr/lib/fpc/3.2.2/, and that's well where the cross-compiler executable is located.

Configuring the compiler.

The Free Pascal compiler settings are stored in /etc/fpc.cfg, and we have to make some modifications to this file to make cross-compilation work correctly. The modifications, I made, are based on the information that I found at the DOS page of the Free Pascal Wiki.

First, find the linking settings and make sure that smartlinking is enabled and that the default binutils prefix is disabled (this code was already part of my fpc.cfg; I just had to add the -XP option):     #ifdef cpui8086         -CX         -XX         -XP     #endif

Then, search for the filename and paths section, and set the search path for units and other system dependent things as follows:     #ifdef cpui8086         -Fu/usr/lib/fpc/$fpcversion/units/$fpctarget/$fpcsubarch-$fpcmemorymodel         -Fu/usr/lib/fpc/$fpcversion/units/$fpctarget/$fpcsubarch-$fpcmemorymodel/*         -Fu/usr/lib/fpc/$fpcversion/units/$fpctarget/$fpcsubarch-$fpcmemorymodel/rtl     #else         -Fu/usr/lib/fpc/$fpcversion/units/$fpctarget         -Fu/usr/lib/fpc/$fpcversion/units/$fpctarget/*         -Fu/usr/lib/fpc/$fpcversion/units/$fpctarget/rtl     #endif

Testing the compiler.

Here a small Pascal program, that we will use to test DOS cross-compilation on our Linux Mint system.     program hello;     uses Crt;     begin         ClrScr;         Writeln; Writeln;         TextColor(Yellow);         Writeln('H E L L O W O R L D !');         TextColor(LightGray);         Writeln; Writeln;     end.

Saving the program as hello.pas to some subfolder in your home directory (I used Programming/Pascal/DOS), you can build the program in a terminal: cd to the directory that contains the Pascal source and run the following command:     ppcross8086 -WmSmall hello.pas

As you can see on the screenshot, compilation and linkage both succeed and the executable hello.exe is created. Trying to run this file fails, of course. These are binaries for DOS 16bit, and it's obvious that these cannot be run on our 64bit Linux system. I then tried hello.exe on MS-DOS 6.22. As the screenshot shows, it works all well!

Note: The size of the executable created (using the small memory model) is 17,120 bytes. As a comparison, using Free Pascal for GO32v2, the same source gives a binary of 54,022 bytes. And last but not least, the executable, produced by good old Borland Pascal 7 with only 3,952 bytes!

Cross-compiling using Geany.

Geany is an IDE commonly used on Linux platforms. It supports syntax highlighting and code completion for several programming languages, as for example C, Java, PHP, Perl, Python, and also Pascal. The build is totally configurable (as is the execution of the created binary). So, we can write our Free Pascal programs in Geany, and set the IDE to use the FPC DOS cross-compiler to build the sources. Lots more comfortable than running terminal commands!

The easiest way to install Geany is to use the Linux Mint Software Manager. Just searching for the package and pushing the Install button...

We can now open hello.pas in Geany and setting the IDE to use our cross-compiler to build Pascal sources. From the IDE menu choose Build > Set Build Commands.

The Set Build Commands window for Pascal files opens, and we can define the following Compile command:     ppcross8086 -WmSmall -Os -Xs "%f" that tells the IDE to build the file actually opened in the editor with the FPC DOS cross-compiler using the small memory model. The other parameters are for size optimization (they seemed not to have an effect with my sample hello.pas program).

And finally, using the menu command Build > Compile, we can build the Free Pascal source code from within Geany.

Testing the executables using DOSBox.

The problem with our cross-compilation is that, each time that we have made changes to the source and rebuilt the program, we'll have to run it in order to see if it works as it should. And the 16bit DOS binaries can't be run as such on Linux, of course. Each time transferring the .exe file to a DOS machine and test it there would be really annoying. And building Linux binaries using the native compiler, that we test in a Mint terminal, hoping that the corresponding DOS binaries behave the same way, is a possible, but obviously far away from optimal possibility. If, instead, we had some way to run the .exe on Linux...

DOSBox is a multiple platform emulation software that allows to run DOS binaries. We can install it using the Linux Mint Software Manager, as we did for Geany.

DOSBox configuration is stored in a file called dosbox-{version}.conf located in the directory /home/{user-name}/.dosbox. Note, that the name of this directory starts with a dot, what, on Unix like platforms, means that it actually is a hidden folder. Thus to view, and eventually edit, it you have to show hidden files (command available in the context menu when you right-click at an empty space in File Explorer). This file really gives you the possibility to set up the DOS environment you want, including the configuration of memory, the sound card, the ports, etc. It also contains a section, where you can add the commands, that on a native DOS system you would add to your autoexec.bat file. The default configuration should work fine in most situation. If you use a non-US keyboard, you should change the keyboard layout (German keyboard in my case).

The screenshots below show DOSBox after start-up (at the left) and some useful information displayed using the intro command (at the right).

How does this emulation software work? In fact, it's really simple: Place your DOS files in a directory somewhere within the native filesystem (on Linux this would normally be a subfolder of your Home directory), then use the DOSBox mount command to mount this directory as a DOS disk drive:     mount {drive-letter} {path-to-DOS-files} As said above, I've created the directory structure Programming/Pascal/DOS in my home directory to place my Free Pascal for DOS related files. So, suppose that I want to access these files in DOSBox as D: drive, the command would be ("allu" being my Linux Mint user name):     mount d /home/allu/Programming/Pascal/DOS

With the D: drive mounted, you can use native DOS commands to access the files, in particular cd to navigate within the folder structure and dir to display a directory's content. The screenshot shows how I do the mount mentioned before, then change from drive Z: (the default DOSBox system drive) to D: and then use the dir command to display my Free Pascal files: hello.pas = sources; hello.a = object code (output of the compiler, before linkage; the extension .a instead of .o is used to explicitly show that smartlinkage has been used); hello.exe = the DOS executable.

Time to test the DOS executable in DOSBox. Being in the root directory of the D: drive, just enter hello. This will make DOS(Box) search first the current directory, then the directories set with the PATH environment variable for a file called hello.exe (or hello.com, or hello.bat) and when it finds it, try to execute it. As you can see, the output of our sample program is exactly the same in DOSBox as it was when running it on MS-DOS 6.22.

Running DOSBox from within Geany.

So far, so good. But, this is still somewhat annoying. It's true, we don't need any longer to transfer the .exe to a DOS system in order to test it, but is it really comfortable that each time we want to do so, we have to leave Geany, switching to DOSBox and run the result of the build there? And even if we have the possibility to mount the drive and automatically navigate to it in the autoexec.bat section of the DOSBox configuration file, we would have to run another mount command to test an executable located somewhere else in the Linux Mint file system. Wouldn't it be lots nicer if we could launch DOSBox and automatically run the executable, resulting from the Free Pascal source build, from within Geany?

This is not only possible, it is also really easy to implement! First, Geany not only gives us the possibility to define a command to be executed when the "Compile" menu item is clicked, but also to define a command for the "Execute" menu item. Second, DOSBox may be started from the command line and gives us the possibility to indicate a command (such as a program name) that is automatically executed when the emulator starts up. This feature is so cleverly set up that the native filesystem directory, where the program to be executed is located, is automatically mounted and the root of the corresponding drive (in fact, the C: drive is used in this case) set as current DOS directory. Amazing!

All we have to do in order to start the DOS executable, resulting from the build, in DOSBox from within Geany is to choose Build > Set Build Commands from the IDE menu, then in the Set Build Commands window for Pascal files, define the following Execute command:     dosbox "%e.exe" that tells Geany to run DOSBox and pass "%e.exe" (that designates the binaries obtained by building the source actually opened in the IDE) as parameter to the emulator.

DOSBox, being called with a full path executable filename as parameter, will use the directory part of this file name to automatically mount this directory as C: drive, sets C:\ as current directory and then runs the program specified by the filename. All we have to do in order to test a 16bit DOS executable build in Geany on Linux Mint is to click the Build > Execute menu command in the IDE! The screenshot shows the result for our hello.pas (hello.exe) Free Pascal sample.

A last remark before terminating this long and hopefully interesting tutorial. Geany does not start the DOSBox GUI directly but runs a terminal and it's from within this terminal that DOSBox is launched. Thus, if you leave DOSBox (using the command exit), you'll see the window of this terminal (it was hidden below the DOSBox window before). Just hit ENTER to close the terminal and return to the Geany IDE.

If you find this text helpful, please, support me and this website by signing my guestbook.