Subsections

- 1 Demo programs and examples
- 2 Supplied programs
  - 1 ppudump program
  - 2 ppumove program
  - 3 ptop - Pascal source beautifier
  - 4 rstconv program
  - 5 fpcmake

#
8 Utilities 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.

# 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.

# 2 Supplied programs

## 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).

## 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.

Its 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.

## 3 ptop - Pascal source beautifier

### 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"

### 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:

- 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.

### 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 its 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 its 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.

## 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.

## 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 its 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.