Geum.ru

Руководство пользователя Free Pascal версии Версия документа Март 2010 Michael Van Canneyt, Florian Klampfl

Вид материалаРуководство пользователя
Подобный материал:
1   2   3   4   5   6   7   8   9   10   ...   16
Раздел 8


Утилиты из комплекта Free Pascal


Кроме компилятора и библиотек времени выполнения Free Pascal имеет в поставке некоторые программы и модули. Ниже приведен перечень этих программ и модулей.


8.1 Демонстрационные программы и примеры


В дистрибутив Free Pascal включен набор демонстрационных программ. Эти программы не имеют другой цели, кроме демонстрации возможностей Free Pascal. Они расположены в каталоге исодников в папке demo.


Все упомянутые в документации примеры программ работают и доступны. Обратите внимание, что все ниже наведенные примеры каталогов находятся в каталоге demo. Их названия заканчиваются на "ex".Там Вы сможете найти исходные коды всех примеров.


8.2 fpcmake


fpcmake это программа для создания makefile из поставки Free Pascal.


Она читает файл конфигурации Makefile.fpc и конвертирует его в Makefile, совместимый с GNU make для компиляции Ваших проектов.


fpcmake принимает параметрами командной строки имена файлов описаний makefile. Для каждого из этих файлов будет создан Makefile в той же директории, где эти файлы находятся (с перезаписью без подтверждения).


Если вы не указали аргументов программе, то она делает попытку прочитать файл Makefile.fpc в текущей директории и пытается создать по нему файл makefile. Любой существовавший до этого makefile будет очищен.


Формат файла конфигурации fpcmake описан с малейшими деталями в дополнениях к Инструкции разработчика (Programmer's Guide).


8.3 fpdoc - программа документации модулей Pascal


fpdoc это программа, которая генерирует полную кросс-справочную документацию для модуля. Она генерирует документацию для каждого идентификатора найденного в разделе Interface модуля. Документация может быть сгенерирована в различных форматах, например HTML, RTF, Text, man-page и LaTeX. В отличие от других инструментов документирования, документация может находиться в отдельном файле (в формате XML), поэтому исходники не загромождаются комментариями.


Сопутствующая fpdoc программа makeskel создает пустой файл XML с элементами для всех идентификаторов, или она может обновлять существующий файл XML добавлением элементов для новых идентификаторов.


fpcdoc и makeskel описаны в FPDoc Reference Guide.


8.4 h2pas - конвертер заголовочных файлов C в модули Pascal


h2pas пытается преобразовать заголовочный файл C в модуль Pascal. Он может работать с большинством конструкций языка С, которые можно найти в файле заголовков, и пытается воспроизвести их в аналогах языка Pascal.


См. ниже (конструкции) для полного описания объема действий, которые может выполнять переводчик. Модуль с кодом на Pascal затем может быть использован для доступа к коду, написанному на C.


Выходной файл h2pas будет иметь то же имя, что и файл заголовков C, который был использован в качестве входных данных, но с расширением .pp. Выходной файл, который создает h2pas может быть настроен в несколько способов с помощью многих опций.


8.4.1 Функции


Вывод h2pas можно управлять с помощью следующих функций:


-d Использовать external для обьявлений всех процедур и функций.


-D Использовать external Libname 'func_name' для объявлений функций и процедур.


-e Возвращать ряд констант вместо типа перечисления для структуры enum.


-i Создать include файл вместо модуля (опускает заголовок модуля).


-l libname указать имя библиотеки для объявлений external функций.


-o outfile Указать имя выходного файла. По умолчанию сохраняется имя входного файла с измененным расширением на ".pp".


-p использовать букву P перед параметрами типа Pointer вместо ..


-s Удалять комментарии во входном файле. По умолчанию комментарии преобразуются в комментарии, но они могут быть смещены, так как комментарии обрабатываются сканером.


-t начинать названия типов с символа "Т" (используется для следования конвенции Borland, что все типы должны быть определены с T).


-v Заменить параметры указателя вызовом по ссылке. Используйте с осторожностью, поскольку некоторые вызовы могут ожидать указатель на nil.


-w Заголовочный файл является заголовочным файлом Win32 (добавлена поддержка некоторых специальных макросов).


-x Обрабатывать SYS_TRAP из заголовочных файлов PalmOS.


8.4.2 Конструкции


Следующие объявления и утверждения C распознаются:


defines Определения (defiine) превращаются в константы Pascal, если они являются простыми определениями. Макросы по возможности заменяются функциями, если аргументы целые числа, иначе они должны быть изменены вручную. Простые арифметические выражения в определениях также распознаются: сложение, вычитание, умножение, деление, логические операторы, операторы сравнения, операторы сдвига. Конструкции С вида (A ? B : C) также распознаются и переводятся на Pascal с использованием ЕСЛИ. (Но это, согласитесь, сложно).


Объявления препроцессора и условные команды препроцессора распознаются и переведены на эквивалентные директивы компилятора Pascal.

Специальное


#ifdef __cplusplus


также распознается и удаляется.


typedef изменяется на type. Распознаются следующие базовые типы:


• char заменяется на char.


• float заменяется на real (=double в Free Pascal).


• int заменяется longint.


• long заменяется на longint.


• long int заменяется на longint.


• short заменяется на integer.


• unsigned заменяется на cardinal.


• unsigned char заменяется на byte.


• unsigned int заменяется на cardinal.


• unsigned long int заменяется на cardinal.


• unsigned short заменятеся на word.


• void игнорируется.


Эти типы также заменяются, если они появляются в аргументах функции или процедуры.


Функции и процедуры также подлежат переводу. Тип указателей может быть изменен на вызов по ссылке (с использованием var у аргумента), используя параметр коммандной строки -р. Функции, которые имеют переменное число аргументов, заменяются на функции с cvar модификатором. (Применяется для использования массива констант в аргументе.)


Также распознаются внешние спецификаторы, но они игнорируются. Спецификатор packed также распознается и заменяется директивой PACKRECORDS. Спецификатор const определяется, но игнорируется.


Модификаторы. Если указан параметр -w, то следующие модификаторы будут обрабатываться:


STDCALL


CDECL


CALLBACK


PASCAL


WINAPI


APIENTRY


WINGDIAPI


как определено в заголовочных файлах Win32. Если дополнительно указан параметр -x, то спецификатор


SYS_TRAP


также распознается.


Конструкции еnum переводятся в перечисления типов. Имейте в виду, что в C перечисление типов могут иметь предопределенные значения. Free Pascal также позволяет делать так в определенной степени. Если Вы знаете, что перечислениям заданы значения, то лучше использовать параметр -е для изменения enum в серию констант типа integer.


Union изменяются в структуры record с использованием variant.


Структуры struct изменяются на Pascal записи, с упаковкой C.


8.5 h2paspp -предпроцессор для h2pas


Программа h2paspp может быть использован как простой препроцессор для h2pas. Она удаляет некоторые из конструкций, которые с которыми h2pas испытывает трудности. h2paspp читает один или несколько файлов заголовочных файлов C и предварительно обрабатывает их, писать результат в файл с тем же именем, что и оригинал. Она не не обрабатывает все знаки C, но заботится о следующих директивах препроцессора:


#define symbol Определяет новый символ символа. Обратите внимание, что макросы не поддерживаются.


#if symbol Текст после этой директивы включен, если символ определен.


#ifdef symbol Текст после этой директивы включен, если символ определен.


#ifndef symbol Текст после этой директивы включен, если символ не определен.


#include filename Директивы include будут удалены, если был дан параметр -I, в этом случае include файл включен и записывается в выходной файл.


#undef symbol Убрать определение символа.


8.5.1 Использование


h2paspp принимает один или несколько файлов и предварительно обрабатывает их. Программа будет читать входные данные, и писать вывод в файл с тем же именем, иначе если задан параметр -o, в этом случае запись идет в указанный файл. Обратите внимание, что можно получить только один выходной файл.


8.5.2 Параметры


h2paspp имеет небольшое число параметров для управления ее поведением:


-d symbol Определить символ symbol перед началом обработки.


-h Отобразить краткую справку.


-I Вложить файлы include вместо директивы include.


-ooutfile Если эта опция задана, вывод будет записан в файл с именем outfile. Обратите внимание, что может быть только один выходной файл.


8.6 Программа ppudump


ppudump это программа, которая показывает содержимое модуля Free Pascal. Она распространяется вместе с компилятором. Можно просто выполнить следующую команду


ppudump [options] foo.ppu


для отображения содержимого модуля foo.ppu. Вы можете указать несколько файлов в командной строке.


Параметры используются для изменения детализации отображения. По умолчанию, отображается вся имеющаяся информация. Вы можете установить уровень подробности использованием параметра -Vxxx. Здесь xxx является сочетанием следующих букв:


h: Отобразить информацию заголовка.


i: Отобразить информацию о секции interface.


m: Отобразить информацию о секции implementation.


d: Отобразить только объявления (только из interface).


s: Отобразить только символы (из interface).


b: Отобразить информацию о браузере.


a: Отобразить все (по умолчанию, но если не указан параметр -V).


8.7 Программа ppumove


ppumove это программа для создания общих или статических библиотек из нескольких модулей. Она похожа на прорамму tpumove, которая поставляется с Turbo Pascal. Он распространяется в бинарном виде вместе с компилятором. Её использование очень простое:


ppumove [options] unit1.ppu unit2.ppu ... unitn.ppu


Где options это комбинация из ниже перечисленного:


-b: Создать командный файл, который будет содержать команды внешних вызовов и архивирования, которые должны быть выполнены. Этот пакетный файл в *nix называется pmove.sh, и pmove.bat в WINDOWS и DOS.


-d xxx: Задать директорию для помещения в нее выходных файлов.


-e xxx: Задать расширение для перемещаемых файлов модулей. По умолчанию это ".ppl". Точку в начале указывать не надо.


-o xxx: Установить имя выходного файла, то есть имя файла, содержащего все модули. Этот параметр является обязательным при использовании нескольких файлов. В Linux, ppumove будет начинать это имя с lib, если оно еще не называлось так, и будет добавлено расширение соответствующего типа библиотеки.


-q: Работать тихо.


-s: Make a static library instead of a dynamic one; By default a dynamic library is made on LINUX.


-w: Tell ppumove that it is working under WINDOWS NT. This will change the names of the linker and archiving program to ldw and arw, respectively.


-h или -?: Отобразить краткую справку.


The action of the ppumove program is as follows: It takes each of the unit files, and modifies it so that the compiler 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


will generate the following output under LINUX:


PPU-Mover Version 2.1.1


Copyright (c) 1998-2007 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 ppu code in the library.


You could then use or distribute the files libboth.so, timer.ppl and ppu.ppl.


8.8 ptop -Pascal source beautifier


8.8.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 Turbo Pascal source beautifiers 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 Write an overview of the possible parameters and command line 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 Set the number of indent spaces used for BEGIN END; and other blocks.


-b bufsize Set the streaming buffersize to bufsize. The default is 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 Write ptop configuration defaults to the file "ptop.cfg". The contents of this file can be changed to your liking, and it can be used with the -c option.


8.8.2 Файл конфигурации ptop


Не обязательно создавать и распостранять файл конфигурации для ptop, если вы не собираетесь изменять стандартное поведение ptop. Файл конфигурации не использется автоматически, поэтому Вам придется указывать в параметрах -c ptop.cfg, если Вы собираетесь его использовать.


Структура конфигурационного файла ptop - это простой повторяющийся раз 20-30 блок для каждого ключевого слова Pascal, извесного программе ptop. (Смотрите стандартный файл конфигурации или исходный код в файле ptopu.pp, чтобы узнать, какие ключевые слова известны программе).


Основной структурный блок конфигурационного файла являет собой одну или две строки, которые описывают, как должен ptop реагировать на конкретное слово. Первой идет строка без квадратных скобок в следующем формате:


keyword=option1,option2,option3,...


Если один из вариантов имеет значение "dindonkey" (см. ниже), тогда понадобится вторая строка (с квадратными скобками):


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


Легко заметить, то блок состоит из двух типов идентификаторов: ключевые слова (keyword и otherkeyword1..3 в примере выше) и варианты (option1..3 выше).


Ключевые слова являют собой встроенные структурные идентификаторы языка Pascal, как BEGIN, END, CASE, IF, THEN, ELSE, IMPLEMENTATION. Стандартный файл конфигурации описывает большинство из них.


Кроме ключевых слов в Pascal используються и другие "слова" для представления операторов и коментариев. (см. Табл. 8.1)


Таблица 8.1: Ключевые слова для операторов


Значение слова Оператор


casevar : метка при выборе (не ’colon’)


becomes :=


delphicomment //


opencomment { или (*


closecomment } или *)


semicolon ;


colon :


equals =


openparen [


closeparen ]


period .


Слова выбора обозначают действие, выполняемое, когда найдено ключевое слово и знак равенства. (см. Табл. 8.2)


Приведенный в Табл. 8.2 вариант "dindonkey" требует дальнейшего объяснения. "dindonkey" - это конструкция "DeINDent ON associated KEYword". Если это слово присутствует как вариант в первой строке, тогда обязательна вторая строка с квадратными скобками. Действие (убирание отсупа, de-indent) в этом случае будет выполнено, когда одно из перечисленных слов во второй строке будет найдено в тексте.


Например: Строки


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


обозначают следующее:


Таблица 8.2: Возможные варианты


Действие


crsupp Подавлять CR (caret return) перед словом.


crbefore Принудительный CR перед словом. (не совмещать с crsupp.)


blinbefore Пустая строка перед словом.


dindonkey Убирать отступ (de-indent) при соответсвующем слове. (см. ниже)


dindent Убирать отступ (deindent) (всегда)


spbef Вставить спереди пробел


spaft Вставить вконце пробел


gobsym Отобразить символы, которые идуть после слова, но ни на что не влияют. Печатать до команды прерывания. (Прерывания сложно описать в pptop и до сих пор нуждаются в переработке)


inbytab Сделать отступ табулятором.


crafter Принудительный CR (caret return) после слова.


upper Отображает слово в ВЕРХНЕМ регистре.


upper Отображает слово в нижнем регистре.


capital Делает первую букву большой, останые маленькие.


dindonkey Убирать отступ (de-indent) при соответсвующем слове. (см. ниже)


• Вариант crbefore сообщает не разрешать остальной код (а только пробелы) перед словом ELSE в той же строке.


• Вариант dindonkey убирает отступ (de-indents) если парсер находит слово из строки с квадратными скобками (if,then,else)


• Вариант inbytab указывает делать оступ табом.


• Вариант upper переводит слово в верхний регистр (else и Else становятся ELSE).


Экспериментируйте с файлом конфигурации шаг за шагом, пока не добьетесь желательного результата. Настраиваемось и возможности ptop довольно велики. Я предпочитаю все ключевые слова заглавными буквами вместо слов с большой буквы, поэтому я по умолчанию заменил capital на upper.


ptop все еще в разработке. Поэтому мудро будет визуально проверить сгенерированный им текст и попробовать его скомпилировать, чтобы увериться, что ptop не сделал каких-либо ошибок.


8.8.3 Модуль ptopu


Исходный код PtoP удобно разделен на два файла: один содержит объект, который собственно и делает улучшения в исходниках, второй является оболочкой вокруг этого объекта, которую можно использовать через командную строку. Такое строение позволяет встроить объект в программу (для примера IDE) и использовать его возможности для форматирования кода.


Объект находиться в модуле PtoPU имеет следующий вид


TPrettyPrinter=Object(TObject)


Indent : Integer; { На сколько симвлов делать отступ? }


InS : PStream;


OutS : PStream;


DiagS : PStream;


CfgS : PStream;


Constructor Create;


Function PrettyPrint : Boolean;


end;


Этот объект очень прост в использовании:


1. Создайте объект, используя его конструктор.


2. Задайте поток InS. Это поток, из которого будет читаться исходный код Pascal. Этот шаг обязательный.


3. Задайте поток OutS. В этот поток будет записан "улучшенный" исходный код Pascal. Этот шаг тоже обязательный.


4. Задайте поток DiagS. Все наблюдения будут записаны в этот поток. Этот шаг не обязателен. Если Вы не зададите его, то наблюдения не будут записаны.


5. Задайте поток CfgS. С этого потока будет прочитана конфигурация. (Смотрите предыдущую секцию, чтобы узнать больше о конфигурации). Этот шаг тоже не обязателен. Если Вы его не зададите, то будет использована конфигурация по умолчанию.


6. Задайте значение Indent (Отступ) - количество пробелов для отступа. Символ табуляции не используется. Этот шаг не обязателен, значение Indent по умолчанию равно 2.


7. Вызовите метод PrettyPrint, который переоформит исходник из InS и запишет результат в OutS. При отсутствии ошибок функция возвратит True, иначе False.


Таким образом, минимальная процедура может быть такой:


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;


Изпользование потоков дает возможность очень быстрого форматирования кода и очень подходит для редакторов.


8.9 Программа rstconv


Программа rstconv конвертирует файлы строковых ресурсов, сгенерированные компилятором (когда вы используете секции строковых ресурсов) в .po файлы, которые может понять программа GNU msgfmt.


rstconv очень проста в использовании, она принимает следующие параметры:


-i file Использовать на вход указанный файл вместо stdin. (не обязательно).


-o file Писать вывод в указаный файл. Этот параметр обязателен.


-f format Задать особый формат вывода. На данный момент поддерживается только один формат вывода: po для GNU gettext ".po" формат. Это формат по умолчанию.


На пример:


rstconv -i resdemo.rst -o resdemo.po


сконвертирует resdemo.rst в resdemo.po.


Больше информации по программе rstconv можно найти в Инструкции Пользователя в статье о строковых ресурсах.


8.10 Программа unitdiff


8.10.1 Краткий обзор


unitdiff показывает отличия между секциями interface двух модулей.


unitdiff [--disable-arguments] [--disable-private] [--disable-protected] [--help] [--lang=language] [--list] [--output=filename] [--sparse] file1 file2


8.10.2 Описание и использование


Unitdiff сканирует исходный код одного или двух модулей Free Pascal и возвращает все идентификаторы или описывает различия идентификаторов между двумя модулями.


Вы можете указать unitdiff только один аргумент - имя входного файла. Тогда он просто вдаст все доступные идентификаторы.


В основном unitdiff вызывается с двумя аргументами.


unitdiff input1 input2


Вызов программы таким образом покажет разницу в секциях interface двух модулей или отобразит список доступных идентификаторов обоих модулей. Вывод unitdiff производится по умолчанию в stdout.


8.10.3 Параметры


Большинство параметров unitdiff не обязательны, потому как вместо их могут использоваться значения по умолчанию.


–disable-arguments Не проверять аргументы функций и процедур. По умолчанию проверка происходит.


–disable-private Не проверять методы и поля классов из секции private. По умолчанию проверка происходит.


–disable-protected Не проверять методы и поля классов из секции protected. По умолчанию проверка происходит.


–help Вывести короткую справку и выйти.


–lang=language Задать язык файла вывода. Это будет в основном набор строк, используемых как заголовки в различных частях файлов документации (по умолчанию они на английском). На данный момент, допустимы следующие значения:


• de: German (Немецкий).


• fr: French (Французский).


• nl: Dutch (Голландский).


–list Отобразить только список доступных идентификаторов из модуля или модулей. Если только один модуль указан в параметрах, то этот параметр применяется автоматически.


–output=filename Указать куда должен производиться вывод. По умолчанию вывод направлен на стандартный вывод (stdout).


–sparse Включить режим sparse. Выводить только названия идентификаторов без их типов и описаний. По умолчанию типы выводятся.