8.2 Supplied programs

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

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.

ptop - Pascal source beautifier

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”
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 (8.1)



Table 8.1: 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 (8.2)

Table 8.2: 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.

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.

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.

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.