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.
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.
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).
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:
- libboth.so : The shared library containing the code from
ppu.o and timer.o. Under WINDOWS NT, this file would be called
both.dll.
- timer.ppl : The unit file that tells the Free Pascal compiler to look
for the timer code in the library.
- 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.
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"
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:
- The keyword this block is about is else because it's on the LEFT side
of both equal signs.
- The option crbefore signals not to allow other code (so just spaces)
before the ELSE keyword on the same line.
- The option dindonkey de-indents if the parser finds any of the keywords
in the square brackets line (if,then,else)
- The option inbytab means indent by a tab.
- The option upper uppercase the keyword (else or Else becomes ELSE)
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.
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:
- Create the object, using it's constructor.
- Set the Ins stream. This is an open stream, from which pascal source will be
read. This is a mandatory step.
- Set the OutS stream. This is an open stream, to which the
beautified pascal source will be written. This is a mandatory step.
- 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.
- 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.
- 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.
- 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.
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.
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.
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.
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.
- 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.
- 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.
- 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.
- 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
