Subsections


8. Utilities and units that come with Free Pascal

Besides the compiler and the Run-Time Library, Free Pascal comes with some utility programs and units. Here we list these programs and units.

8.1 Demo programs and examples

Also distributed with Free Pascal comes a series of demonstration programs. These programs have no other purpose than demonstrating the capabilities of Free Pascal. They are located in the demo directory of the sources.

All example programs of the documentation are available. Check out the directories that end on ex in the documentation sources. There you will find all example sources.

8.2 Supplied programs

8.2.1 ppudump program

ppudump is a program which shows the contents of a Free Pascal unit. It is distributed with the compiler. You can just issue the following command

  ppudump [options] foo.ppu
to display the contents of the foo.ppu unit. You can specify multiple files on the command line.

The options can be used to change the verbosity of the display. By default, all available information is displayed. You can set the verbosity level using the -Vxxx option. Here, xxx is a combination of the following letters:

h:
show header info.
i:
show interface information.
m:
show implementation information.
d:
show only (interface) definitions.
s:
show only (interface) symbols.
b:
show browser info.
a:
show everything (default if no -V option is present).

8.2.2 ppumove program

ppumove is a program to make shared or static libraries from multiple units. It can be compared with the tpumove program that comes with Turbo Pascal.

It should be distributed in binary form along with the compiler.

It's usage is very simple:

ppumove [options] unit1.ppu unit2.ppu ... unitn.ppu
Where options is a combination of
-b:
If specified, ppumve will generate a batch file that will contain the external linking and archiving commands that must be executed. The name of this batch file is pmove.sh on LINUX, and pmove.bat otherwise.
-d xxx:
If specified, the output files will put in the directory xxx
-e xxx:
Sets the extension of the moved unit files to xxx. By default, this is .ppl. You don't have to specify the dot.
-o xxx:
sets the name of the output file, i.e. the name of the file containing all the units. This parameter is mandatory when you use multiple files. On LINUX, ppumove will prepend this name with lib if it isn't already there, and will add an extension appropriate to the type of library.
-q:
Causes ppumove to operate silently.
-s:
Tells ppumove to make a static library instead of a dynamic one; By default a dynamic library is made on LINUX.
-w:
Tells ppumove that it is working under WINDOWS NT. This will change the names of te linker and archiving program to ldw and arw, respectively.
-h or -?:
will display a short help.

The action of the ppumve program is as follows: It takes each of the unit files, and modifies it so that the compile will know that it should look for the unit code in the library. The new unit files will have an extension .ppu, this can be changed with the -e option. It will then put together all the object files of the units into one library, static or dynamic, depending on the presence of the -s option.

The name of this library must be set with the -o option. If needed, the prefix lib will be prepended under LINUX.. The extension will be set to .a for static libraries, for shared libraries the extensions are .so on linux, and .dll under WINDOWS NT and OS/2.

As an example, the following command

./ppumove -o both -e ppl ppu.ppu timer.ppu
under linux, will generate the following output:
PPU-Mover Version 0.99.7
Copyright (c) 1998 by the Free Pascal Development Team

Processing ppu.ppu... Done.
Processing timer.ppu... Done.
Linking timer.o ppu.o
Done.
And it will produce the following files:
  1. libboth.so : The shared library containing the code from ppu.o and timer.o. Under WINDOWS NT, this file would be called both.dll.
  2. timer.ppl : The unit file that tells the Free Pascal compiler to look for the timer code in the library.
  3. ppu.ppl : The unit file that tells the Free Pascal compiler to look for the timer code in the library.
You could then use or distribute the files libboth.so, timer.ppl and ppu.ppl.

8.2.3 ptop - Pascal source beautifier

8.2.3.1 ptop program

ptop is a source beautifier written by Peter Grogono based on the ancient pretty-printer by Ledgard, Hueras, and Singer, modernized by the Free Pascal team (objects, streams, configurability etc)

This configurability, and the thorough bottom-up design are the advantages of this program over the diverse TurboPascal sourcebeautifiers on e.g. SIMTEL.

The program is quite simple to operate:

ptop "[-v] [-i indent] [-b bufsize ][-c optsfile] infile outfile"

The Infile parameter is the pascal file to be processed, and will be written to outfile, overwriting an existing outfile if it exists.

Some options modify the behaviour of ptop:

-h
Writes an overview of the possible parameters and commandline syntax.
-c ptop.cfg
Read some configuration data from configuration file instead of using the internal defaults then. A config file is not required, the program can operate without one. See also -g.
-i ident
Sets the number of indent spaces used for BEGIN END; and other blocks.
-b bufsize
Sets the streaming buffersize to bufsize. Default 255, 0 is considered non-valid and ignored.
-v
be verbose. Currently only outputs the number of lines read/written and some error messages.
-g ptop.cfg
Writes a default configuration file to be edited to the file "ptop.cfg"

8.2.3.2 The ptop configuration file

Creating and distributing a configuration file for ptop is not necesarry, unless you want to modify the standard behaviour of ptop. The configuration file is never preloaded, so if you want to use it you should always specify it with a -c ptop.cfg parameter.

The structure of a ptop configuration file is a simple buildingblock repeated several (20-30) times, for each pascal keyword known to the ptop program. (see the default configuration file or ptopu.pp source to find out which keywords are known)

The basic building block of the configuration file consists out of one or two lines, describing how ptop should react on a certain keyword. First a line without square brackets with the following format:

keyword=option1,option2,option3,...

If one of the options is "dindonkey" (see further below), a second line (with square brackets) is needed like this:

[keyword]=otherkeyword1,otherkeyword2,otherkeyword3,...

As you can see the block contains two types of identifiers, keywords(keyword and otherkeyword1..3 in above example) and options, (option1..3 above).

Keywords are the built-in valid Pascal structure-identifiers like BEGIN, END, CASE, IF, THEN, ELSE, IMPLEMENTATION. The default configuration file lists most of these.

Besides the real Pascal keywords, some other codewords are used for operators and comment expressions. table (keywords)


Table: keywords for operators
Name of codeword operator  
casevar : in a case label ( unequal 'colon')  
becomes :=  
delphicomment //  
opencomment { or (*  
closecomment } or *)  
semicolon ;  
colon :  
equals =  
openparen [  
closeparen ]  
period .  

The Options codewords define actions to be taken when the keyword before the equal sign is found, table (options)


Table: Possible options
Option does what  
crsupp suppress CR before the keyword.  
crbefore force CR before keyword  
  (doesn't go with crsupp :) )  
blinbefore blank line before keyword.  
dindonkey de-indent on associated keywords  
  (see below)  
dindent deindent (always)  
spbef space before  
spaft space after  
gobsym Print symbols which follow a  
  keyword but which do not  
  affect layout. prints until  
  terminators occur.  
  (terminators are hard-coded in pptop,  
  still needs changing)  
inbytab indent by tab.  
crafter force CR after keyword.  
upper prints keyword all uppercase  
lower prints keyword all lowercase  
capital capitalizes keyword: 1st letter  
  uppercase, rest lowercase.  

The option "dindonkey" requires some extra parameters, which are set by a second line for that option (the one with the square brackets), which is therefore is only needed if the options contain "dinkdonkey" (contraction of de-indent on assiociated keyword).

"dinkdonkey" deindents if any of the keywords specified by the extra options of the square-bracket line is found.

Example: The lines

else=crbefore,dindonkey,inbytab,upper
[else]=if,then,else

mean the following:

Try to play with the configfile step by step until you find the effect you desire. The configurability and possibilities of ptop are quite large. E.g. I like all keywords uppercased instead of capitalized, so I replaced all capital keywords in the default file by upper.

ptop is still development software, so it is wise to visually check the generated source and try to compile it, to see if ptop hasn't made any errors.

8.2.3.3 ptopu unit

The source of the PtoP program is conveniently split in two files: One is a unit containing an object that does the actual beautifying of the source, the other is a shell built around this object so it can be used from the command line. This design makes it possible to include the object in some program (e.g. an IDE) and use it's features to format code.

The object resided in the PtoPU unit, and is declared as follows

  TPrettyPrinter=Object(TObject)
      Indent : Integer;    { How many characters to indent ? }
      InS    : PStream;
      OutS   : PStream;
      DiagS  : PStream;
      CfgS : PStream;
      Constructor Create;
      Function PrettyPrint : Boolean;
    end;

Using this object is very simple. The procedure is as follows:

  1. Create the object, using it's constructor.
  2. Set the Ins stream. This is an open stream, from which pascal source will be read. This is a mandatory step.
  3. Set the OutS stream. This is an open stream, to which the beautified pascal source will be written. This is a mandatory step.
  4. Set the DiagS stream. Any diagnostics will be written to this stream. This step is optional. If you don't set this, no diagnostics are written.
  5. Set the Cfgs stream. A configuration is read from this stream. (see the previous section for more information about configuration). This step is optional. If you don't set this, a default configuration is used.
  6. Set the Indent variable. This is the number of spaces to use when indenting. Tab characters are not used in the program. This step is optional. The indent variable is initialized to 2.
  7. Call PrettyPrint. This will pretty-print the source in Ins and write the result to OutS. The function returns True if no errors occurred, False otherwise.

So, a minimal procedure would be:

Procedure CleanUpCode;

var
  Ins,OutS : PBufStream;
  PPRinter : TPrettyPrinter;

begin
  Ins:=New(PBufStream,Init('ugly.pp',StopenRead,TheBufSize));
  OutS:=New(PBufStream,Init('beauty.pp',StCreate,TheBufSize));
  PPrinter.Create;
  PPrinter.Ins:=Ins;
  PPrinter.outS:=OutS;
  PPrinter.PrettyPrint;
end;

Using memory streams allows very fast formatting of code, and is perfectly suitable for editors.

8.2.4 rstconv program

The rstconv program converts the resource string files generates by the compiler (when you use resource string sections) to .po files that can be understood by the GNU msgfmt program.

Its usage is very easy; it accepts the following options:

-i file
Use the specified file instead of stdin as input file. This option is optional.
-o file
write output to the specified file. This option is required.
-f format
Specifies the output format. At the moment, only one output format is supported: po for GNU gettext .po format. It is the default format.
As an example:
rstconv -i resdemo.rst -o resdemo.po
will convert the resdemo.rst file to resdemo.po.

More information on the rstconv utility can be found in the Programmers' guide, under the chapter about resource strings.

8.2.5 fpcmake

fpcmake is the Free Pascal makefile constructor program.

It reads a Makefile.fpc configuration file and converts it to a Makefile suitable for reading by GNU make to compile your projects. It is similar in functionality to GNU autoconf or Imake for making X projects.

fpcmake accepts filenames of makefile description files as it's command-line arguments. For each of these files it will create a Makefile in the same directory where the file is located, overwriting any other existing file.

If no options are given, it just attempts to read the file Makefile.fpc in the current directory and tries to construct a makefile from it. any previously existing Makefile will be erased.

The format of the fpcmake configuration file is described in great detail in the appendices of the Programmers' guide.

8.3 Supplied units

Here we list the units that come with the Free Pascal distribution. Since there is a difference in the supplied units per operating system, we list them separately per system. They are documented in the Unit reference.

8.3.1 Units common to all platforms

The following units are common to all platform; i.e. their workings are guaranteed to be the same on all platforms.
getopts
This unit gives you the GNU getopts command-line arguments handling mechanism. It also supports long options.
mmx
This unit provides support for mmx extensions in your code.
objects
This unit provides basic routines for handling objects.
objpas
is used for Delphi compatibility; you should never load this unit explicitly; it is automatically loaded if you request Delphi mode.
ports
provides access to the PC hardware ports.
strings
This unit provides basic string handling routines for the pchar type, comparable to similar routines in standard C libraries.
sysutils
is an alternative implementation of the sysutils unit of Delphi.
typinfo
Provides functions to acces Run-Time Type Information, just like Delphi.

8.3.2 Under DOS

crt
This unit provides basic screen handling routines. It provides the same functionality as the Turbo Pascal CRT unit.
dos
This unit provides basic routines for accessing the operating system DOS. It provides almost the same functionality as the Turbo Pascal unit.
emu387
This unit provides support for the coprocessor emulator.
graph
This unit provides basic graphics handling, with routines to draw lines on the screen, display texts etc. It provides the same functions as the Turbo Pascal unit.
go32
This unit provides access to possibilities of the GO32 DOS extender.
printer
This unit provides all you need for rudimentary access to the printer.

8.3.3 Under Windows

dos
This unit provides basic routines for accessing the operating system DOS. It emulates this functionality by issuing calls to the Windows operating system.
crt and wincrt
These units provides basic screen handling routines. They provide the same functionality as the Turbo Pascal CRT unit.
graph
This unit provides basic graphics handling, with routines to draw lines on the screen, display texts etc. It provides the same functions as the Turbo Pascal unit.
Windows
This unit provides access to al Win32 API calls. Effort has been taken to make sure that it is compatible to the Delphi version of this unit, so code for Delphi is easily ported to Free Pascal.
opengl
provides access to the low-level opengl functions in WINDOWS.
winmouse
provides access to the mouse in WINDOWS.
ole2
provides access to the OLE capabilities of WINDOWS.
winsock
provides acces to the WINDOWS sockets API Winsock.
sockets
is a wrapper around winsock that is compatible with the LINUX sockets layer. Using this unit ensures that your code will run both on WINDOWS and LINUX.

8.3.4 Under Linux

crt
This unit provides basic screen handling routines. It provides the same functionality Turbo Pascal CRT unit. It should work on any terminal which supports the vt100 escape sequences.
dos
This unit provides an emulation of the same unit under DOS. It is intended primarily for easy porting of Pascal programs from DOS to LINUX. For good performance, however, it is recommended to use the linux unit.
linux
This unit provides access to the LINUX operating system. It provides most file and I/O handling routines that you may need. It implements most of the standard C library constructs that you will find on a Unix system. If you do a lot of disk/file operations, the use of this unit is recommended over the one you use under Dos.
printer
This unit provides an interface to the standard Unix printing mechanism. It supports printing to file and to any command you would like.
sockets
This unit gives you access to sockets and TCP/IP programming.
graph
Is an implementation of Borlands graph unit, which works on the Linux console. It's implementation is as complete as on the other platforms (it shares the same code). It uses the libvga and libvgagl graphics libraries, so you need these installed for this unit to work. Also, programs using this library need to be run as root, or setuid root, and hence are a potential security risk.
ports
This implements the various port[] constructs. These are provided for compatibility only, and it is not recommended to use them extensively. Programs using this construct must be run as ruit or setuid root, and are a serious security risk on your system.

8.3.5 Under OS/2

doscalls
interface to doscalls.dll.
dive
interface to dive.dll
emx
provides access to the EMX extender.
pm*
interface units for the program manager functions.
viocalls
interface to viocalls.dll screen handling library.
moucalls
interface to moucalls.dll mouse handling library.
kbdcalls
interface to kbdcalls.dll keyboard handling library.
moncalls
interface to moncalls.dll monitoring handling library.



root
2000-12-20