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

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



Смотрите также:
Комплекс «Энергосфера» Программное обеспечение «Сервер опроса» Руководство пользователя Версия...
GARMIN GPSMAP 60 Руководство пользователя...
Руководство пользователя Версия 0 Санкт-Петербург 2010 Фирма зао «Взлет»...
Программный комплекс «Банк-Клиент» imb-link tcp/ip руководство пользователя версия 1...
Руководство пользователя Версия 86060401...
Руководство пользователя программы «OracleAdmin» 37 4 Руководство пользователя программы...
Руководство пользователя Учет посещаемости и успеваемости студентов...
Системной Энциклопедии" Руководство пользователя "...
Инструкция и документация версия 92 данное руководство недостаточно адаптировано с версии 2...
Версия программы or4t31-4 прибор приемно-контрольный охранно-пожарный «орион-4Т 1» руководство...
Руководство пользователя Версия 4...
Руководство пользователя Версия 01...



страницы: 1   2   3   4   5   6   7   8   9   10
вернуться в начало
скачать
Глава 6


Интегрированная среда разработки (Integrated Development Environment)


Интегрированная среда разработки (далее просто IDE) предоставляет удобный пользовательский интерфейс к компилятору. Она состоит из редактора с подсветкой синтаксиса, отладчика, обозревателя имён/идентификаторов. IDE (поставляемая вместе с компилятором FreePascal) это приложение которое работает в текстовом режиме и выглядят одинаково под всем поддерживаемыми операционными системами. Она смоделирована по образу IDE из состава Turbo Pascal, поэтому многие будут чувствовать себя комфортабельно используя ее.


На данный момент среда разработки (IDE) доступна для DOS, Windows и Linux.


6.1 Первые шаги.


6.1.1 Запуск среды разработки.


Среда запускается следующей командой:


fp


введенной в командной строке. Также ее можно запустить используя графический интерфейс, такой как в Windows.


Замечание: В Windows, есть возможность переключатся между оконным и полноэкранным режимом нажимая комбинацию Alt-Enter.


6.1.2 Параметры командной строки для среды


Запуская среду, ей можно передавать параметры:


fp [-option] [-option] ... ...


Опциями могут быть любые из списка ниже(опции не чувствительны к регистру):


-N (только для DOS) не использовать длинные имена файлов. WINDOWS 95 и более поздние версии WINDOWS предоставляют интерфейс DOS приложениям для доступа к длинным именам файлов. Среда использует этот интерфейс по умолчанию. При определенных обстоятельствах, это может приводить к проблемам. Этот параметр говорит Среде не использовать длинные имена файлов.


-Cfilename (имя файла) Читает параметры среды с указанного файла. Здесь не должно быть пробела между именем файла и параметром -C.


-F использовать альтернативный набор графических символов. Эта опция может быть использована для запуска Среды под LINUX из X-term или через сессию телнет.


-R После запуска Среды, автоматически изменяется активный каталог на тот, который был активным при выходе в последний раз.


-S Отключить мышь. Когда эта опция включена, использование мыши выключено, даже если мышь присутствует.


-Tttyname (имя терминала)(только для LINUX/Unix) Отправляет вывод программы на tty(терминал) ttyname. Это позволяет избежать необходимости постоянно переключаться между выходом программы и IDE.


Файлы, указанные в командной строке загружаются в окна редактирования автоматически.


Примечание: В DOS/Win32, первым символом опции командной строки может быть символ /. Так /S эквивалентно -S.


6.1.3 Экран Среды


После запуска, экран среды может выглядеть как на рисунке (6.1).


Рисунок 6.1: Экран Среды после запуска.


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


Строка состояния показывает комбинации клавиш для часто используемых команд, и обеспечивает быстрый доступ к этим командам, щелкая по ним мышью. На правом краю строки состояния, отображается текущее количество неиспользуемой памяти. Это всего лишь индикатор, так как IDE пытается выделить больше памяти, если ее не хватает.


Меню предоставляет доступ ко всем возможностям Среды, а на правом краю меню отображаются часы.


Из Среды можно выйти выбрав в меню "File|Exit" или нажав комбинацию 1 ALT-X.


Примечание: Если файл fp.ans находится в текущем каталоге, то он будет загружен и используется для рисования фона. Этот файл должен содержать ANSI рисунок для рисования на экране.


1 "File | Exit" означает выберите пункт "Exit" в меню "File".


6.2 Навигация в Среде. Средой можно управлять как с клавиатуры так и с помощью мыши, если система оснащена ею.


6.2.1 Использование клавиатуры


Весь функционал Среды доступен через использование клавиатуры.


• Она используется как для набора текста так и для навигации по исходному тексту.


• Команды редактирования, такие как копирование и вставка текста.


• Перемещение и смена размеров окон.


• Она может быть использована для доступа к меню, при удержании клавиши ALT и соответствующей выделенной буквы в меню, или нажатии клавиши F10 и навигации по меню с помощью клавиш перемещения курсора.


• Много команд Среды имеют клавишную комбинацию быстрого вызова, т.е. нажатие специальных комбинаций клавиш сразу выполнит команду закрепленную за ней.


Примечание:


• При работе в Linux X-Term или через Telnet сессии, клавишные комбинации с ALT могут быть недоступны. Чтобы исправить это, нужно сначала нажать комбинацию CTRL-Z. Это значит что комбинация ALT-X может быть заменена на CTRL-Z X.


• Кроме того, вы можете попробовать комбинацию клавиш ESC-X для Alt-X при работе на LINUX.


Полное описание всех горячих клавиш можно найти в разделе 6.14, стр. 88.


6.2.2 Использование мыши


Если система оснащена мышью, она может быть использована для работы с IDE. Левая кнопка используется для выбора пунктов меню, нажатия кнопок, выбора текстовых блоков и т.д.


Правая кнопка мыши используется для доступа к контекстному меню, если таковое имеется. Удерживая нажатой клавишу CTRL или ALT и нажав правую кнопку мыши будут выполняться пользовательские функции. См. раздел 6.12.4, стр. 85.


Примечание:


1. Иногда, руководство использует термин "перетащить мышью". Это означает, что мышь перемещается в то время как левая кнопка мыши нажата.


2. Действия кнопки мыши могут быть инвертированы, т. е. действия левой кнопкой мыши могут быть отнесены к правой кнопке мыши и наоборот. В данном руководстве предполагается, что действия кнопки мыши не будут инвертированы.


3. Мышь не всегда доступна, даже если мышь установлена:


• Среда работает под LINUX через Telnet соединение с WINDOWS машиной.


• IDE работает под Linux, в X-term под X-Windows. В этом случае все зависит от программы эмулятора терминала: под Konsole (терминала KDE) он работает.


См. раздел 6.12.4, стр. 85 для получения дополнительной информации о том, как инвертировать действия кнопки мыши.


В Windows, консоль имеет опцию "Быстрое редактирование", что позволяет скопировать текст в буфер обмена, выделив текст в окне консоли. Если этот режим включен, мышь не будет работать. Опция "Быстрое редактирование" должна быть отключена в свойствах консоли окна для того, чтобы Среда получала события мыши.


6.2.3 Навигация в диалогах


Диалоги, как правило, имеют много элементов, таких как: кнопки, поля ввода, многострочные поля ввода, списки и так далее. Для активации одного из этих полей, нужно использовать один из следующих методов:


1. Нажмите на элемент с помощью мыши.


2. Нажимайте клавишу TAB пока нужный элемент не получит фокус ввода.


3. Нажмите букву подсвеченную в имени элемента. Если фокус находится на элементе, который позволяет редактировать, тогда следует нажимать одновременно ALT и подсвеченную букву. Для кнопки, будет выполнено связанное с кнопкой событие.


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


6.3 Окна


В настоящее время, работа с оконными приложениями не должна быть проблемой для большинства пользователей WINDOWS и Linux. Тем не менее, в следующем разделе описывается, как работать с окнами, чтобы получить максимальную выгоду от Среды разработки Free Pascal.


6.3.1 Основы


Окно Среды отображено на рисунке (6.2)


Рисунок 6.2: Окно Среды


Окна окружены так называемой рамкой, белой двойной линией вокруг окна. В верхней части окна отображаются следующие вещи:


• В левом верхнем углу окна, отображается значок закрытия. При нажатии на него окно будет закрыто. Окно также может быть закрыто нажатием ALT-F3 или выбрав пункт меню "Window|Close"("Окно|Закрыть"). Все открытые окна могут быть закрыты, выбрав пункт меню "Window|Close all"("Окно|Закрыть все").


• Посередине отображается заголовок окна.


В правом верхнем углу, отображается число. Это число определяэт окно редактора, и при нажатии ALT-ЧИСЛО будет осуществлен переход к этому окну. Таким образом можно получить доступ только к первым 9 окнам.


• В правом верхнем углу, отображается маленькая зеленая стрелка. При нажатии на эту стрелку окно масштабируется так,что оно охватывает весь рабочий стол. При нажатии на эту стрелку при развернутом окне будет восстановлен ее старый размер. Нажатие клавиши F5 имеет тот же эффект, как щелчок на стрелке. Тот же эффект может быть достигнут при выборе пункта меню "Window | Zoom". Окна и диалоги, которые нельзя изменить, не могут быть увеличены.


На правом и нижнем краям окна содержатся полосы прокрутки. Они могут быть использованы для прокрутки содержимого окна с помощью мыши. Стрелки на концах полосы прокрутки можно нажать для прокрутки содержимого окна строка за строкой. При нажатии на пунктирной области между стрелками и прямоугольнике голубого цвета будет прокручиваться содержимое окна страница за страницей. При перемещении прямоугольника содержание можно прокручивать непрерывно.


Звезда и номера в левом нижнем углу окна отображают информацию о содержимом окна. Они описаны в разделе о редакторе, см. раздел 6.5, стр. 50.


6.3.2 Изменение размера и перемещения окон


Окна можно перемещать и изменять размер с помощью мыши и клавиатуры. Чтобы переместить окно:


• Использование мыши, нажмите на строку заголовка и перетащите окно с помощью мыши.


• Использование клавиатуры, перейдите в режим размера/перемещения, нажав Ctrl-F5 или выбрав пункт меню "Window|Size/Move"("Окно|размер/переместить"). Цвет оконной рамы изменится на зеленый, чтобы указать, что Среда в режиме размера/перемещения. Теперь клавиши управления курсором можно использовать для перемещения окна. Нажмите кнопку ENTER, чтобы покинуть режим размера/перемещения. В этом случае, окно сохранит его размер и положение. Кроме того, нажатие ESC восстановит старые позиции.


Смена размера окон:


• Использование мыши, щелкните на нижнем правом углу окна и перетащите его.


• Использование клавиатуры, перейдите в режим размера/перемещения, нажав Ctrl-F5 или выбрав пункт меню "Window|Size/Move"("Окно|размер/переместить"). Оконная рамка поменяет цвет на зеленый, чтобы указать, что Среда в режиме размера/перемещения. Теперь нужно удерживая SHIFT нажать одну из клавиш управления курсором, чтобы изменить размер окна. Нажмите кнопку ENTER, чтобы покинуть режим размер/перемещения. Нажатие ESC восстановит старые размеры.


Не все окна могут изменять размер. Это относится, например, к диалоговым окнам (раздел 6.3.4, стр. 43).


Окна также могут быть скрыты. Чтобы скрыть окно, можно использовать сочетания клавиш Ctrl-F6, или выбрать пункт меню "Window|Hide"("Окно|Скрыть"). Чтобы восстановить скрытое окно, необходимо выбрать его из списка окон. Более подробную информацию о списке окон можно найти в следующем разделе.


6.3.3 Работа с несколькими окнами


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


Неактивное окно определяется по серой рамки. Неактивное окно делается активным одним из следующих способов:


• Использование мыши, активировать окно, щелкнув по нему.


• Использование клавиатуры, нажатие клавиши F6 позволяет пройтись по всем открытым окнам. Для активации предыдущего активного окна нужно нажать Shift-F6.


• Пункт меню "Window|Next" может быть использован для активации следующего окна в списке окон, а "Window|Previous" выбора предыдущее окно.


• Если окно имеет номер в правом верхнем углу, оно может быть активировано нажатием ALT-ЧИСЛО.


• При нажатии Alt-0 появится диалог со списком всех доступных окон, он позволяет быстро активировать окна, которые не имеют номера.


Окна могут быть упорядочены и размещены на рабочем столе Среды путем масштабирования и изменения их размера с помощью мыши или клавиатуры. Это трудоемкая задача, и особенно при использовании клавиатуры. Вместо этого, могут быть использованы пункты меню"Window|Tile" ("Окно|Плитка") и "Window|Cascade"("Окно|Каскад") :


Tile(плитка) разделит все пространство рабочего стола равномерно между всеми окнами.


Cascade поставит все окна в каскадном расположении.


В очень редких случаях экран Среды может стать запутанным. В этом случае весь экран Среды может быть обновлен, выбрав пункт меню "Window|Refresh display"("Окно|Обновить экран").


6.3.4 Диалоговые окна


Во многих случаях Среда отображает диалоговое окно для получения пользовательского ввода. Основным отличием от обычных окон является то, что другие окна не могут быть активированы в то время как диалог является активным. Также нет доступа к меню пока открыто диалоговое окно. Такое поведение называется модальным. Для активации другого окна, модальное окно или диалог должно быть закрыто.


Типичное диалоговое окно показано на рисунке (6.3).


6.4 Меню


Главное меню (серая панель в верхней части Среды) обеспечивает доступ ко всем функциональностям Среды. Оно также содержит часы, отображающие текущее время. Меню всегда доступно, кроме случаев, когда открыто диалоговое окно. Если открыто диалоговое окно, его нужно сначала закрыть чтобы получить доступ к меню.


В некоторых окнах, также доступны контекстные меню. Оно появляться возле курсора, а также предоставляет дополнительные команды, которые являются контекстно-зависимыми.


6.4.1 Доступ к меню


К меню можно получить доступ в несколько способов:


Рисунок 6.3: типичное диалоговое окно


1. При использовании мыши для выбора пунктов меню. Курсор мыши должен быть расположен над нужным пунктом меню, и нажатием левой кнопки мыши затем выбрать его.


2. Через нажатие клавиши F10. Это переключит фокус ввода на меню. Клавишами управления курсором(стрелки) можно перемещаться по меню. Клавиша ENTER должна быть использована для выбора пункта.


3. Для непосредственного доступа к элементам меню, может быть использована комбинация клавиш ALT-<выделенная в меню буква>. После выпадания подменю можно выбрать нужный элемент, нажав непосредственно выделенную букву без ALT. Например Alt-S G является быстрым способом вызова диалога перехода к указанной строчке кода.


К каждому пункту меню отображается краткий текст разъяснения в строке состояния. Если доступно контекстном меню, доступ к нему можно получить нажатием правой кнопки мыши или комбинации ALT-F10. Для выхода из любого меню без каких-либо действий, нажмите клавишу ESC два раза. Все пункты меню и их действия описаны далее.


6.4.2 меню File(Файл)


Меню "File"("Файл") содержит все пункты меню, которые позволяют пользователю загружать и сохранять файлы, а также дают возможность покинуть Среду.


New(Новый) Открывает новое, пустое окно редактора.

New from template(Новый из шаблона) Предлагает шаблон, который будет использоваться, просит заполнить некоторые параметры, а затем откраивает новое окно редактора с шаблоном.

Open (F3)(Открыть) Открывает диалог выбора файла, и открывает выбранный файл в новом окне редактора.

Print(Печать) Печать содержимого текущего окна редактирования.

Print setup(Настройка печати) настроить свойства принтера.

Reload Перезагрузить файл с диска.

Save (F2)(Сохранить) Сохраняет содержимое текущего окна редактирования в текущий файл. Если текущее окно редактирования еще не не связано с файлом, диалог предложит ввести новое имя файла.

Save as Отобразит диалог, в котором можно ввести имя файла. Содержимое текущего окна сохраняются в новый файл, а введенное имя файла используется для дальнейшего сохранения файла.

Save all Сохраняет содержимое всех окон редактирования.


Change dir Отобразит диалог, в котором можно выбрать каталог. Текущий рабочий каталог изменится на выбранный каталог.


Command shell Выполняет командную оболочку. После выхода из оболочки, Среда возобновит свою роботу. Какая командная оболочка запустится зависит от системы.


Exit (ALT-X) Завершает работу Среды. Если в редакторе будут не сохраненные файлы, Среда спросит нужно ли их сохранить.


Под меню "Exit" появляются некоторые имена недавно использованных файлов. Эти записи могут быть использованы для быстрой загрузки недавно закрытых файлов в редактор.


6.4.3 меню Правка


Меню "Правка" содержит записи для доступа к буферу обмена, а также отмены или повтора действий редактирования.


Большинство из этих функций имеют сочетания клавиш, связанные с ними.


Undo(Отменить) (ALT-BKSP) Отменяет последнее действие редактирования. Действия по редактированию хранятся в буфере. ???Выбор этого механизма будет двигаться в обратном направлении через этот буфер, то есть возможны несколько уровней отмены . Однако, любое выделение, что, возможно, было сделано не будет воспроизводятся.


Redo(Повторить) Повторяет последнее действие, которое было отменено командой Undo(Отменить). ??


Cut (Shift-Del) Удаляет выделенный текст из окна и копирует его в буфер обмена. Любое предыдущее содержимое буфера обмена, будет потеряно. Новое содержание буфера обмена доступно для вставки в другом месте.


Copy (Ctrl-Ins) Копирует текущее выделение в буфер обмена. Любое предыдущее содержимое буфера обмена, будет потеряно. Новое содержание буфера обмена доступно для вставки в другом месте.


Paste (Shift-Ins) Вставляет текущее содержимое буфера обмена в текст в позицию курсора. Содержимое буфера обмена остается, прежним.


Clear (Ctrl-Del) Очищает(т.е. удаляет) текущее выделение.


Select All(Выделить все) Выделяет весь текст в текущем окне. Выделенный текст может быть скопирован или вырезан в буфер обмена.


Unselect отменить выделение.


Show clipboard Открывает окно, в котором показано текущее содержимое буфера обмена.


При запуске Среды под Windows, меню "Edit"(Правка ) имеет два дополнительных элемента. Среда поддерживает отдельный буфер обмена, который не разделяет его содержимое с буфером обмена Windows. Чтобы получить доступ к буферу обмена Windows, присутствуют следующие две записи :


Copy to Windows Скопировать выделенный фрагмент в буфер обмена Windows.


Paste from Windows Вставить содержимое буфера обмена Windows (если он содержит текст) в окно редактирования в текущую позицию курсора.


6.4.4 меню Поиск


Меню "Search"("Поиск") обеспечивает доступ к диалогу поиска и замены, а также доступ к обозревателю имён IDE.


Find (CTRL-Q F) Показывает диалог поиска. Здесь можно вводить искомый текст, когда диалог будет закрыт, будет осуществлен поиск введенного текста в активном окне. Если текст найден, он будет выделен.


Replace (CTRL-Q A) Показывает диалог поиска и замены. После закрытия диалога, в активном окне искомый текст будет заменен на текст замены.


Search again (CTRL-L) Повторяет последние действие поиска или поиска и замены, используя те же параметры.


Go to line number (ALT-G) Предлагает ввести номер строки, а затем переходит к строке с указанным номером.


Когда программа и модули скомпилированы с ?отладочной информацией?, тогда будут доступны следующие пункты меню:


Find procedure(найти процедуру) Пока не реализовано.


Objects Спрашивает имя объекта и открывает окно просмотра для данного объекта.


Modules Спрашивает имя модуля и открывает окно просмотра для данного модуля.


Globals Спрашивает имя глобального идентификатора и открывает окно просмотра для этого глобального идентификатора.


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


6.4.5 меню Выполнить


Меню "Run"("Выполнить") содержит все пункты, связанные с запуском программы,


Run (CTRL-F9) Если исходные тексты были изменены, компилирует программу. Если компиляция прошла успешно, программа будет выполнена. ?If the primary file was set, then that is used to determine which program to execute?. См. раздел 6.4.6, стр. 47 для получения дополнительной информации о том, как установить ?первичный? файл.


Step over (F8) Выполнить программу до следующей строки исходного кода. Если в тексте встречаются вызовы процедур то они будут полностью выполнены.


Trace into (F7) Выполнить текущую строку. Если текущая строка содержит вызов другой процедуры, процесс остановится на точке входа вызываемой процедуры.


Goto cursor (F4) Выполнит программу до строки в которой стоит курсор.


Until return Выполняет текущую процедуру до точки выхода из нее.


Run directory Устанавливает рабочую папку для программы, которая будет активной во время выполнения программы.


Parameters Позволяет вводить параметры, которые будут переданы программе при запуске.


Program reset (CTRL-F2) если программа выполняется или отлаживается, сеанс отладки прерывается, и запущенная программа остановливается.


6.4.6 Меню компиляция


Меню "Compile"(компиляция ) содержит все записи, относящиеся к компиляции программы или модуля.


Compile (ALT-F9) Компилирует содержимое активного окна, независимо от настроек в основном файле.


Make (F9) Компилирует содержимое активного окна, и все зависящие файлы, модули или программы, которые были изменены с момента последней компиляции. ??


Build Компилирует содержимое активного окна, и все зависящие файлы, модули или программы, вне зависимости от того были ли они изменены или нет. ?If the primary file was set, the primary file is compiled instead. ?


Target Устанавливает целевую операционную систему, для которой программа должна быть скомпилирована.


Primary file Sets the primary file. If set, any run or compile command will act on the primary file instead of on the active window. The primary file need not be loaded in the IDE for this to have effect.


Clear primary file Clears the primary file. After this command, any run or compile action will act on the active window.


Compiler messages (F12) Отображает окно сообщений компилятора. Это окно будет отображать сообщения, сгенерированные компилятором во время последней компиляции.


6.4.7 меню Debug(Отладка)


Меню "Debug" содержит пункты меню оказывающие помощь в отладке программы, такие как задание точек останова и просмотр значений переменных.


Output Show Отображает в окне вывод программы пользователя.


User screen (ALT-F5) Переключает на экран, в котором отображается вывод последней запущенной программы .


Add watch (CTRL-F7) Добавляет наблюдение???. Наблюдение это выражение, которое может быть вычислено IDE и будет показано в отдельном окне. Обычно это значение некоторой переменной.


Watches Показывает текущий список наблюдений в отдельном окне.


Breakpoint (CTRL-F8) Устанавливает точку останова на текущей строке. При отладке, выполнение программы будет остановлено на этой точке строке.


Breakpoint list Показывает текущий список точек останова в отдельном окне.


Call stack (CTRL-F3) Показывает стек вызовов. Стек вызовов это список адресов (и имена файлов и номера строк, если эта информация была включена) процедур, которые в настоящее время вызваны в программе.


Disassemble Показывает стек вызовов.


Registers Показывает текущее содержимое регистров процессора.


Floating point unit Показывает текущее содержание FPU регистров.


Vector unit Показывает текущее содержание MMX (или эквивалентных) регистров.


GDB window Показывает консоль отладчика GDB. Оно может быть использовано, чтобы взаимодействовать с отладчиком непосредственно, здесь могут быть введены произвольные команды GDB а результат будет показан в окне.


6.4.8 меню Tools(Инструменты)


Меню "Tools" определяет некоторые стандартные инструменты. Если новые инструменты определяются пользователем, они добавляются к этому меню.


Messages (F11) Показывает окно сообщений. Это окно содержит вывод одного из инструментов. Дополнительные сведения см. в разделе 6.10.1, стр. 62.


Goto next (ALT-F8) Переход к следующему сообщению.


Goto previous (ALT-F7) Переход к предыдущему сообщению.


Grep (SHIFT-F2) Предоставляет возможность вводить регулярные выражения и опции, которые будут переданы программе grep при запуске. Чтобы это работало, программа grep должна быть установлена в системе, и должна быть в каталоге, который прописан в переменной PATH. Дополнительные сведения см. в разделе 6.10.2, стр. 63.


Calculator Отображает калькулятор. Дополнительные сведения см. в разделе 6.10.4, стр. 64.


Ascii table Отображение таблицу ASCII символов. Дополнительные сведения см. в разделе 6.10.3, стр. 63.


6.4.9 Меню Options(параметры)


Меню "Options" является отправной точкой для всех диалогов, которые используются для настройки параметров компилятора и IDE, а также пользовательских настроек.


Mode Показывает диалог установки текущего режима компилятора. Текущий режим отображается с правой стороны меню. Дополнительные сведения см. в разделе 6.11.8, стр. 80.


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


Memory sizes Показывает диалоговое окно, где могут быть установлены размер стека и динамической памяти. Эти параметры будут использоваться при компиляции программы.


Linker Показывает диалог, в котором могут быть установлены некоторые параметры компоновщика. Эти параметры будут использоваться, когда программа или модуль компилируется.


Debugger Показывает диалог, в котором могут быть заданы параметры отладки. Эти параметры используются при компиляции модулей или программ. Обратите внимание, что отладчик не будет работать, без отладочной информации созданной для программы.


Directories Показывает диалог, в котором задаются каталоги необходимые компилятору. Эти каталоги будут использоваться, когда программа или модуль компилируется.


Browser Показывает диалог в котором можно задать параметры обозревателя. Параметры обозревателя влияют на поведение обозревателя символов в IDE.


Tools Показывает диалог в котором можно настраивать меню "tools". Дополнительные сведения см. в разделе 6.10.5, стр. 65.


Environment Показывает диалог в котором можно настраивать поведение IDE. Представлено подменю с различными аспектами IDE:


Preferences General предпочтения, например, следует ли сохранять файлы автоматически или нет, и какие файлы должны быть сохранены. Также здесь можно задать режим видео.


Editor Управление различными параметрами окна редактирования.


CodeComplete Используется для автоматического дополнения слов в набираемом тексте.


Codetemplates Используется для определения шабонов программного кода, которые могут быть вставлены в окно редактирования.


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


Keyboard & Mouse Can be used to select the cut/copy/paste convention, control the actions of the mouse, and to assign commands to various mouse actions.


Learn keys Let the IDE learn keystrokes to be assigned to various commands. This is useful mostly on LINUX and Unix-like platforms, where the actual keys sent to the IDE depend on the terminal emulation.


Open Presents a dialog in which a file containing editor preferences can be selected. After the dialog is closed, the preferences file will be read and the preferences will be applied.


Save Сохранение текущих параметров в файле по умолчанию.


Save as Сохранение текущих параметров в другом файле. Появлятеся диалог сохранения, где должно быть указано имя файла.


Будьте внимательны! Параметры не сохраняются автоматически. Для явного сохранения параметров воспользуйтесь командой меню "Options|Save".


Меню Window


Меню "Window" обеспечивает доступ к некоторым функциям управления открытыми окнами. Более подробную информацию можно найти в главе 6.3, стр. 41


Tile "Замостить" рабочий стол открытыми окнами.

Cascade Расположить открытые окна каскадом.

Close all Закрывает все открытые окна

Size/move (CTRL-F5) Puts the IDE in Size/move mode; after this command the active window can be moved and resized using the arrow keys.

Zoom (F5) Zooms or unzooms the current window.


Next (F6) Activates the next window in the window list.


Previous (SHIFT-F6) Activates the previous window in the window list.


Hide (CTRL-F6) Hides the active window.


Close (ALT-F3) Closes the active window.


List (ALT-0) Shows the list of opened windows. From there a window can be activated, closed, shown and hidden.


Refresh Перерисовать рабочий стол.


Меню справка "Help"


The "Help" menu provides entry points to all the help functionality of the IDE, as well as the means to customize the help system.


Contents Перейти к оглавлению справки.

Index (SHIFT-F1) Jumps to the help Index.

Topic search (CTRL-F1) Jumps to the topic associated with the currently highlighted text.


Previous topic (ALT-F1) Jumps to the previously visited topic.


Using help Displays help on using the help system.


Files Allows the configuration of the help menu. With this menu item, help files can be added to the help system.

About Displays information about the IDE. See section 6.13.3, page 87 for more information.


6.5 Редактирование текста


In this section, the basics of editing (source) text are explained. The IDE works like many other text editors in this respect, so mainly the distinguishing points of the IDE will be explained.


6.5.1 Режимы вставки


Normally, the IDE is in insert mode. This means that any text that is typed will be inserted before text that is present after the cursor.


In overwrite mode, any text that is typed will replace existing text.


When in insert mode, the cursor is a flat blinking line. If the IDE is in overwrite mode, the cursor is a cube with the height of one line. Switching between insert mode and overwrite mode happens with the INSERT key or with the CTRL-V key.


6.5.2 Блоки


The IDE handles selected text just as the Turbo Pascal IDE handles it. This is slightly different from the way e.g. WINDOWS applications handle selected text.


Текст можно выделить тремя способами:


1. Используя мышь. При помощи левой кнопки мыши выделить текст.


2. При помощи клаватуры. Нажмите Ctrl+K B, чтобы перейти в режим выделения текста, затем нажмите Ctrl+K K чтобы закончить выделение.


3. При помощи клавиатуры. Удерживайте кнопку Shift и при помощи клавиш курсора выделите текст.


There are also some special select commands:


1. The current line can be selected using CTRL-K L.


2. The current word can be selected using CTRL-K T.


In the Free Pascal IDE, selected text is persistent. After selecting a range of text, the cursor can be moved, and the selection will not be destroyed; hence the term ’block’ is more appropriate for the selection, and will be used henceforth...


Several commands can be executed on a block:


• Move the block to the cursor location (CTRL-K V).


• Copy the block to the cursor location (CTRL-K C).


• Delete the block (CTRL-K Y).


• Write the block to a file (CTRL-K W).


• Read the contents of a file into a block (CTRL-K R). If there is already a block, this block is not replaced by this command. The file is inserted at the current cursor position, and then the inserted text is selected.


• Indent a block (CTRL-K I).


• Undent a block (CTRL-K U).


• Print the block contents (CTRL-K P).


When searching and replacing, the search can be restricted to the block contents.


6.5.3 Setting bookmarks


The IDE provides a feature which allows the setting of a bookmark at the current cursor position. Later, the cursor can be returned to this position by pressing a keyboard shortcut.


Up to 9 bookmarks per source file can be set up; they are set by CTRL-K (where number is the number of the bookmark). To go to a previously set bookmark, press CTRL-Q .


Remark: Currently, the bookmarks are not saved when the IDE is exited. This may change in future implementations of the IDE.


6.5.4 Jumping to a source line


It is possible to go directly to a specific source line. To do this, open the goto line dialog via the "Search|Goto line number" menu.


In the dialog that appears, the line number the IDE should jump to can be entered. The goto line dialog is shown in figure (6.4).


Figure 6.4: The goto line dialog.


6.5.5 Подстветка синтаксиса


The IDE is capable of syntax highlighting, i.e. the color of certain Pascal elements can be set. As text is entered in an editor window, the IDE will try to recognise the elements, and set the color of the text accordingly.


The syntax highlighting can be customized in the colors preferences dialog, using the menu option "Options|Environment|Colors". In the colors dialog, the group "Syntax" must be selected. The item list will then display the various syntactical elements that can be colored:


Whitespace The empty text between words. Note that for whitespace, only the background color will be used.

Comments All styles of comments in Free Pascal.


Reserved words All reserved words of Free Pascal. (See also Reference Guide).


Strings Constant string expressions. Numbers Numbers in decimal notation.


Hex numbers Numbers in hexadecimal notation.


Assembler Any assembler blocks.


Symbols Recognised symbols (variables, types).


Directives Compiler directives.


Tabs Tab characters in the source can be given a different color than other whitespace.


The editor uses some default settings, but experimentation is the best way to find a suitable color scheme. A good color scheme helps in detecting errors in sources, since errors will result in wrong syntax highlighting.


6.5.6 Code Completion


Code completion means the editor will try to guess the text as it is being typed. It does this by checking what text is typed, and as soon as the typed text can be used to identify a keyword in a list of keywords, the keyword will be presented in a small colored box under the typed text. Pressing the ENTER key will complete the word in the text.


There is no code completion yet for filling in function arguments, or choosing object methods as in e.g. the Lazarus or Delphi IDEs. Code completion can be customized in the Code completion dialog, reachable through the menu option "Options|Preferences|Codecomple". The list of keywords that can be completed can be maintained here. The code completion dialog is shown in figure (6.5).


The dialog shows in alphabetical order the currently defined keywords that are available for completion.


The following buttons are available:


Ok Saves all changes and closes the dialog.


Edit Pops up a dialog that allows the editing of the currently highlighted keyword.


New Pops up a dialog that allows the entry of a new keyword which will be added to the list.


Delete Deletes the currently highlighted keyword from the list.


Cancel Discards all changes and closes the dialog.


All keywords are saved and are available the next time the IDE is started. Duplicate names are not allowed. If an attempt is made to add a duplicate name to the list, an error will follow.


Figure 6.5: The code completion dialog.


6.5.7 Шаблоны программного кода


Шаблоны программного кода служат для вставки больших фрагментов кода в текст программы. Каждому шаблону присваивается уникальное имя. Это имя используется в дальнейшем для вставки соответствующего программного кода в текст программы.


Например имя шаблона "ifthen" может ассоциироваться со следующим кодом:


If | Then


begin


end


Шаблон можно добавить, начав писать имя шаблона в тексте программы; нажатием Ctrl+J, когда курсор установлен справа от имени шаблона.


If there is no template name before the cursor, a dialog will pop up to allow selection of a template.


If a vertical bar (|) is present in the code template, the cursor is positioned on it, and the vertical bar is deleted. In the above example, the cursor would be positioned between the if and then, ready to type an expression.


Code templates can be added and edited in the code templates dialog, reachable via the menu option "Options|Environment|CodeTemplates". The code templates dialog is shown in figure (6.6).


The top listbox in the code templates dialog shows the names of all known templates. The bottom half of the dialog shows the text associated with the currently highlighted code template. The following buttons are available:


Ok Saves all changes and closes the dialog.


Edit Pops up a dialog that allows the editing of the currently highlighted code template. Both the name and text can be edited.


New Pops up a dialog that allows the entry of a new code template which will be added to the list. A name must be entered for the new template.


Delete Deletes the currently highlighted code template from the list.


Cancel Discards all changes and closes the dialog.


Figure 6.6: The code templates dialog.


All templates are saved and are available the next time the IDE is started.


Remark: Duplicates are not allowed. If an attempt is made to add a duplicate name to the list, an error will occur.


6.6 Searching and replacing


The IDE allows you to search for text in the active editor window. To search for text, one of the following can be done:


1. Select "Search|Find" in the menu.


2. Press CTRL-Q F.


After that, the dialog shown in figure (6.7) will pop up, and the following options can be entered:


Text to find The text to be searched for. If a block was active when the dialog was started, the first line of this block is proposed.


Case sensitive When checked, the search is case sensitive.


Whole words only When checked, the search text must appear in the text as a complete word.


Direction The direction in which the search must be conducted, starting from the specified origin.


Scope Specifies if the search should be on the whole file, or just the selected text.


Origin Specifies if the search should start from the cursor position or the start of the scope.


Figure 6.7: The search dialog.


After the dialog has closed, the search is performed using the given options. A search can be repeated (using the same options) in one of 2 ways:


1. Select "Search|Search again" from the menu.


2. Press CTRL-L.


It is also possible to replace occurrences of a text with another text. This can be done in a similar manner to searching for a text:


1. Select "Search|Replace" from the menu.


2. Press CTRL-Q A.


A dialog, similar to the search dialog will pop up, as shown in figure (6.8). Figure 6.8: The replace dialog.


In this dialog, in addition to the things that can be filled in in the search dialog, the following things can be entered:


New text Text that will replace the found text.


Prompt on replace Before a replacement is made, the IDE will ask for confirmation.


If the dialog is closed with the ’OK’ button, only the next occurrence of the the search text will be replaced. If the dialog is closed with the ’Change All’ button, all occurrences of the search text will be replaced.


6.7 The symbol browser


The symbol browser allows searching all occurrences of a symbol. A symbol can be a variable, type, procedure or constant that occurs in the program or unit sources.


To enable the symbol browser, the program or unit must be compiled with browser information. This can be done by setting the browser information options in the compiler options dialog.


The IDE allows to browse several types of symbols:


Procedures Allows quick jumping to a procedure definition or implementation.


Objects Quickly browse for an object.


Modules Browse a module.


Globals Browse any global symbol.


Arbitrary symbol Browse an arbitrary symbol.


In all cases, first a symbol to be browsed must be selected. After that, a browse window appears. In the browse window, all locations where the symbol was encountered are shown. Selecting a location and pressing the space bar will cause the editor to jump to that location; the line containing the symbol will be highlighted.


If the location is in a source file that is not yet displayed, a new window will be opened with the source file loaded.


After the desired location has been reached, the browser window can be closed with the usual commands.


The behaviour of the browser can be customized with the browser options dialog, using the "Options|


Browser" menu. The browser options dialog looks like figure (6.9).


The following options can be set in the browser options dialog:


Symbols Here the types of symbols displayed in the browser can be selected:


Labels Labels are shown.


Constants Constants are shown.


Types Types are shown.


Variables Variables are shown.


Procedures Procedures are shown.


Inherited


Sub-browsing Specifies what the browser should do when displaying the members of a complex symbol such as a record or class:


New browser The members are shown in a new browser window.


Figure 6.9: The browser options dialog.


Replace current The contents of the current window are replaced with the members of the selected complex symbol.


Preferred pane Specifies what pane is shown in the browser when it is initially opened:


Scope


Reference


Display Determines how the browser should display the symbols:


Qualified symbols


Sort always Sorts the symbols in the browser window.


6.8 Running programs


A compiled program can be run straight from the IDE. This can be done in one of several ways:


1. select the "Run|Run" menu, or


2. press CTRL-F9.


If command line parameters should be passed to the program, then these can be set through the "Run|Parameters" menu. The program parameters dialog looks like figure (6.10).


Figure 6.10: The program parameters dialog.


Once the program has started, it will continue to run, until


1. the program quits normally,


2. an error happens,


3. a breakpoint is encountered, or


4. the program is reset by the user.


The last alternative is only possible if the program is compiled with debug information.


Alternatively, it is possible to position the cursor somewhere in a source file, and run the program till the execution reaches the source line where the cursor is located. This can be done by


1. selecting "Run|Goto Cursor" in the menu,


2. pressing F4.


Again, this is only possible if the program was compiled with debug information.


The program can also executed line by line. Pressing F8 will execute the next line of the program. If the program wasn’t started yet, it is started. Repeatedly pressing F8 will execute the program line by line, and the IDE will show the line to be executed in an editor window. If somewhere in the code a call occurs to a subroutine, then pressing F8 will cause the whole routine to be executed before control returns to the IDE. If the code of the subroutine should be stepped through as well, then F7 should be used instead. Using F7 will cause the IDE to execute line by line any subroutine that is encountered.


If a subroutine is being stepped through, then the "Run|Until return" menu will execute the program till the current subroutine ends.


If the program should be stopped before it quits by itself, then this can be done by


1. selecting "Run|Program reset" from the menu, or


2. pressing CTRL-F2.

The running program will then be aborted.


6.9 Debugging programs


To debug a program, it must be compiled with debug information. Compiling a program with debug information allows you to:


1. Execute the program line by line.


2. Run the program up to a certain point (a breakpoint).


3. Inspect the contents of variables or memory locations while the program is running.


6.9.1 Using breakpoints


Breakpoints will cause a running program to stop when the execution reaches the line where the breakpoint was set. At that moment, control is returned to the IDE, and it is possible to continue execution.


To set a breakpoint on the current source line, use the "Debug|Breakpoint" menu entry, or press CTRL-F8.


Figure 6.11: The breakpoint list window


A list of current breakpoints can be obtained through the "Debug|Breakpoint list" menu. The breakpoint list window is shown in figure (6.11).


In the breakpoint list window, the following things can be done:


New Shows the breakpoint property dialog where the properties for a new breakpoint can be entered.


Edit Shows the breakpoint property dialog where the properties of the highlighted breakpoint can be changed.


Delete Deletes the highlighted breakpoint.


The dialog can be closed with the ’Close’ button. The breakpoint properties dialog is shown in figure


(6.12) Figure 6.12: The breakpoint properties dialog


The following properties can be set:


Type Set the type of the breakpoint. The following types of breakpoints exist:


function Function breakpoint. The program will stop when the function with the given name is reached.


file-line Source line breakpoint. The program will stop when the source file with given name and line is reached.


watch Expression breakpoint. An expression may be entered, and the program will stop as soon as the expression changes.


awatch (access watch) Expression breakpoint. An expression that references a memory location may be entered, and the program will stop as soon as the memory indicated by the expression is accessed.


Address stop as soon as an address is reached.


rwatch (read watch) Expression breakpoint. An expression that references a memory location may be entered, and the program will stop as soon as the memory indicated by the expression is read.


Name Name of the function or file where to stop.


Conditions Here an expression can be entered which must evaluate to True for the program to stop at the breakpoint. The expressions that can be entered must be valid GDB expressions.


Line Line number in the file where to stop. Only for breakpoints of type file-line.


Ignore count The number of times the breakpoint will be ignored before the program stops.


Remark:


1. Because the IDE uses GDB to do its debugging, it is necessary to enter all expressions in uppercase.


2. Expressions that reference memory locations should be no longer than 16 bytes on LINUX or go32v2 on an Intel processor, since the Intel processor’s debug registers are used to monitor these locations.


3. Memory location watches will not function on Win32 unless a special patch is applied.


6.9.2 Using watches


When debugging information is compiled in the program, watches can be used. Watches are expressions which can be evaluated by the IDE and shown in a separate window. When program execution stops (e.g. at a breakpoint) all watches will be evaluated and their current values will be shown.


Setting a new watch can be done with the "Debug|Add watch" menu command or by pressing CTRL-F7. When this is done, the watch property dialog appears, and a new expression can be entered. The watch property dialog is shown in figure (6.13).


In the dialog, the expression can be entered. Any possible previous value and current value are shown.


Remark: Because the IDE uses GDB to do its debugging, it is necessary to enter all expressions in uppercase in FREEBSD.


A list of watches and their present value is available in the watches window, which can be opened with the "Debug|Watches" menu. The watch list window is shown in figure (6.14).


Pressing ENTER or the space bar will show the watch property dialog for the currently highlighted watch in the watches window.


The list of watches is updated whenever the IDE resumes control when debugging a program.


Figure 6.13: The watch property dialog


Figure 6.14: The watch list window.


6.9.3 The call stack


The call stack helps in showing the program flow. It shows the list of procedures that are being called at this moment, in reverse order. The call stack window can be shown using the "Debug|Call Stack" menu. It will show the address or procedure name of all currently active procedures with their filename and addresses. If parameters were passed they will be shown as well. The call stack is shown in figure (6.15).


By pressing the space bar in the call stack window, the line corresponding to the call will be highlighted in the edit window.


6.9.4 The GDB window


The GDB window provides direct interaction with the GDB debugger. In it, GDB commands can be typed as they would be typed in GDB. The response of GDB will be shown in the window.


Some more information on using GDB can be found in section 10.2, page 119, but the final reference is of course the GDB manual itself 3. The GDB window is shown in figure (6.16).


Available from the Free Software Foundation website.


Figure 6.15: The call stack window.


Figure 6.16: The GDB window


6.10 Using Tools


The tools menu provides easy access to external tools. It also has three pre-defined tools for programmers: an ASCII table, a grep tool and a calculator. The output of the external tools can be accessed through this menu as well.


6.10.1 The messages window


The output of the external utilities is redirected by the IDE and it will be displayed in the messages window. The messages window is displayed automatically, if an external tool was run. The messages window can also be displayed manually by selecting the menu item "Tools|Messages" or by pressing the F11 key. The messages window is shown in figure (6.17).


If the output of the tool contains filenames and line numbers, the messages window can be used to navigate the source as in a browse window:


1. Pressing ENTER or double clicking the output line will jump to the specified source line and close the messages window.

Figure 6.17: The messages window


2. Pressing the space bar will jump to the specified source line, but will leave the messages window open, with the focus on it. This allows the quick selection of another message line with the arrow keys and jump to another location in the sources.


The algorithm which extracts the file names and line numbers from the tool output is quite sophisticated, but in some cases it may fail4.


6.10.2 Grep


One external tool in the Tools menu is already predefined: a menu item to call the grep utility ("Tools|Grep" or SHIFT-F2). Grep searches for a given string in files and returns the lines which contain the string. The search string can even be a regular expression. For this menu item to work, the grep program must be installed, since it is not distributed with Free Pascal.


The messages window displayed in figure (6.17) in the previous section shows the output of a typical grep session. The messages window can be used in combination with grep to find special occurrences in the text.


Grep supports regular expressions. A regular expression is a string with special characters which describe a whole class of expressions. The command line in DOS or LINUX has limited support for regular expressions: entering ls *.pas (or dir *.pas) to get a list of all Pascal files in a directory. *.pas is something similar to a regular expression. It uses a wildcard to describe a whole class of strings: those which end on ".pas". Regular expressions offer much more: for example [A-Z][0-9]+ describes all strings which begin with an upper case letter followed by one or more digits.


It is outside the scope of this manual to describe regular expressions in great detail. Users of a LINUX system can get more information on grep using man grep on the command line.


6.10.3 The ASCII table


The tools menu also provides an ASCII table ("Tools|Ascii table"). The ASCII table can be used to look up ASCII codes as well as to insert characters into the window which was active when invoking the table.


To reveal the ASCII code of a character in the table, move the cursor onto this character or click it with the mouse. The decimal and hex values of the character are shown at the bottom on the ASCII table window.


To insert a character into an editor window either:


1. using the mouse, double click it, or,


2. using the keyboard, press ENTER while the cursor is on it. (Suggestions for improvement, or better yet, patches that improve the algorithm, are always welcome.)


This is especially useful for pasting graphical characters in a constant string. The ASCII table remains active till another window is explicitly activated; thus multiple characters can be inserted at once. The ASCII table is shown in figure (6.18).


Figure 6.18: The ASCII table


6.10.4 The calculator


The calculator allows quick calculations without leaving the IDE. It is a simple calculator, since it does not take care of operator precedence, and bracketing of operations is not (yet) supported.


The result of the calculations can be pasted into the text using the CTRL-ENTER keystroke. The calculator dialog is shown in figure (6.19).


The calculator supports all basic mathematical operations such as addition, subtraction, division and multiplication.


6.10.5 Adding new tools


The tools menu can be extended with any external program which is command line oriented. The output of such a program will be caught and displayed in the messages window.


Adding a tool to the tools menu can be done using the "Options|Tools" menu. This will display the tools dialog. The tools dialog is shown in figure (6.20).


In the tools dialog, the following actions are available:


New Shows the tool properties dialog where the properties of a new tool can be entered.


Edit Shows the tool properties dialog where the properties of the highlighted tool can be edited.


Delete Removes the currently highlighted tool.


Cancel Discards all changes and closes the dialog.


OK Saves all changes and closes the dialog.


The definitions of the tools are written in the desktop configuration file. So unless auto-saving of the desktop file is enabled, the desktop file should be saved explicitly after the dialog is closed.


6.10.6 Meta parameters


When specifying the command line for the called tool, meta parameters can be used. Meta parameters are variables and and they are replaced by their contents before passing the command line to the tool.


$CAP Captures the output of the tool.

$CAP_MSG() Captures the output of the tool and puts it in the messages window.

$CAP_EDIT() Captures the output of the tool and puts it in a separate editor window.

$COL Replaced by the column of the cursor in the active editor window. If there is no active window or the active window is a dialog, then it is replaced by 0.

$CONFIG Replaced by the complete filename of the current configuration file.

$DIR() Replaced by the full directory of the filename argument, including the trailing directory separator. e.g. $DIR(’d:\data\myfile.pas’) would return d:\data\.

$DRIVE() Replaced by the drive letter of the filename argument. e.g. $DRIVE(’d:\data\myfile.pas’) would return d:.

$EDNAME Replaced by the complete file name of the file in the active edit window. If there is no active edit window, this is an empty string.


$EXENAME Replaced by the executable name that would be created if the make command was used. (i.e. from the ’Primary File’ setting or the active edit window).

$EXT() Replaced by the extension of the filename argument. The extension includes the dot. e.g. $EXT(’d:\data\myfile.pas’) would return .pas.

$LINE Replaced by the line number of the cursor in the active edit window. If no edit window is present or active, this is 0.

$NAME() Replaced by the name part (excluding extension and dot) of the filename argument. e.g. $NAME(’d:\data\myfile.pas’) would return myfile.

$NAMEEXT() Replaced by the name and extension part of the filename argument. e.g. $NAMEEXT(’d:\data\myfile.pas’) would return myfile.pas.

$NOSWAP Does nothing in the IDE; it is provided only for compatibility with Turbo Pascal.

$PROMPT() Prompt displays a dialog box that allows editing of all arguments that come after it. Arguments that appear before the $PROMPT keyword are not presented for editing. $PROMPT() can also take an optional filename argument. If present, $PROMPT() will load a dialog description from the filename argument. E.g. $PROMPT(cvsco.tdf) would parse the file cvsco.tdf, construct a dialog with it and display it. After the dialog closed, the information entered by the user is used to construct the tool command line. See section 6.10.7, page 68 for more information on how to create a dialog description.


$SAVE Before executing the command, the active editor window is saved, even if it is not modified.


$SAVE_ALL Before executing the command, all unsaved editor files are saved without prompting.


$SAVE_CUR Before executing the command the contents of the active editor window are saved without prompting if they are modified.


$SAVE_PROMPT Before executing the command, a dialog is displayed asking whether any unsaved files should be saved before executing the command.


$WRITEMSG() Writes the parsed tool output information to a file with name as in the argument.


6.10.7 Building a command line dialog box


When defining a tool, it is possible to show a dialog to the user, asking for additional arguments, using the $PROMPT(filename) command-macro. The Free Pascal distribution contains some ready-made dialogs, such as a ’grep’ dialog, a ’cvs checkout’ dialog and a ’cvs check in’ dialog. The files for these dialogs are in the binary directory and have an extension .tdf.


In this section, the file format for the dialog description file is explained. The format of this file resembles a windows .INI file, where each section in the file describes an element (or control) in the dialog. An OK and a Cancel button will be added to the bottom of the dialog, so these should not be specified in the dialog definition.


A special section is the Main section. It describes how the result of the dialog will be passed to the command line, and the total size of the dialog.


Remark: Keywords that contain a string value should have the string value enclosed in double quotes as in


Title="Dialog title"


The Main section should contain the following keywords:


Title The title of the dialog. This will appear in the frame title of the dialog. The string should be enclosed in quotes.


Size The size of the dialog, this is formatted as (Cols,Rows), so Size=(59,9) means the dialog is 59 characters wide, and 9 lines high. This size does not include the border of the dialog.


CommandLine specifies how the command line will be passed to the program, based on the entries made in the dialog. The text typed here will be passed on after replacing some control placeholders with their values.


A control placeholder is the name of some control in the dialog, enclosed in percent (%) characters.


The name of the control will be replaced with the text associated with the control. Consider the following example:


CommandLine="-n %l% %v% %i% %w% %searchstr% %filemask%"


Here the values associated with the controls named l, v, i, w and searchstr and filemask will be inserted in the command line string.


Default The name of the control that is the default control, i.e. the control that is to have the focus when the dialog is opened.


The following is an example of a valid main section:


[Main]


Title="GNU Grep"


Size=(56,9)


CommandLine="-n %l% %v% %i% %w% %searchstr% %filemask%"


Default="searchstr"


After the Main section, a section must be specified for each control that should appear on the dialog. Each section has the name of the control it describes, as in the following example:


[CaseSensitive]


Type=CheckBox


Name="~C~ase sensitive"


Origin=(2,6)


Size=(25,1)


Default=On


On="-i"


Each control section must have at least the following keywords associated with it:


Type The type of control. Possible values are:


Label A plain text label which will be shown on the dialog. A control can be linked to this label, so it will be focused when the user presses the highlighted letter in the label caption (if any).


InputLine An edit field where a text can be entered.


CheckBox A checkbox which can be in an on or off state.


Origin Specifies where the control should be located in the dialog. The origin is specified as (left,top) and the top-left corner of the dialog has coordinate (1,1) (not counting the frame).


Size Specifies the size of the control, which should be specified as (Cols,Rows).


Each control has some specific keywords associated with it; they will be described below.


A label (Type=Label) has the following extra keywords associated with it:


Text the text displayed in the label. If one of the letters should be highlighted so it can be used as a shortcut, then it should be enclosed in tilde characters (.). E.g. in


Text="~T~ext to find"


the T will be highlighted.


Link The name of a control in the dialog may be specified. If specified, pressing the label’s highlighted letter in combination with the ALT key will put the focus on the control specified here.


A label does not contribute to the text of the command line; it is for informational and navigational purposes only. The following is an example of a label description section:


[label2]


Type=Label


Origin=(2,3)


Size=(22,1)


Text="File ~m~ask"


Link="filemask"


An edit control (Type=InputLine) allows entry of arbitrary text. The text of the edit control will be pasted in the command line if it is referenced there. The following keyword can be specified in a inputline control section:


Value A standard value (text) for the edit control can be specified. This value will be filled in when the dialog appears.


The following is an example of an input line section:


[filemask]


Type=InputLine


Origin=(2,4)


Size=(22,1)


Value="*.pas *.pp *.inc"


A checkbox control (Type=CheckBox) presents a checkbox which can be in one of two states, on or off. With each of these states, a value can be associated which will be passed on to the command line. The following keywords can appear in a checkbox type section:


Name The text that appears after the checkbox. If there is a highlighted letter in it, this letter can be used to set or unset the checkbox using the ALT-letter combination.


Default Specifies whether the checkbox is checked or not when the dialog appears (value on or off).


On The text associated with this checkbox if it is in the checked state.


Off The text associated with this checkbox if it is in the unchecked state.


The following is an example of a valid checkbox description:


[i]


Type=CheckBox


Name="~C~ase sensitive"


Origin=(2,6)


Size=(25,1)


Default=On


On="-i"


If the checkbox is checked, then the value -i will be added on the command line of the tool. If it is unchecked, no value will be added.


6.11 Project management and compiler options


Project management in Pascal is much easier than with C. The compiler knows from the source which units, sources etc. it needs. So the Free Pascal IDE does not need a full featured project manager like some C development environments offer. Nevertheless there are some settings in the IDE which apply to projects.


6.11.1 The primary file


Without a primary file the IDE compiles/runs the source of the active window when a program is started. If a primary file is specified, the IDE always compiles/runs this source, even if another source window is active. With the menu item "Compile|Primary file..." a file dialog can be opened where the primary file can be selected. Only the menu item "Compile|Compile" compiles the active window regardless. This is useful if a large project is being edited, and only the syntax of the current source should be checked.


The menu item "Compiler|Clear primary file" restores the default behaviour of the IDE, i.e. the ’compile’ and ’run’ commands apply to the active window.


6.11.2 The directory dialog


In the directory dialog, the directories can be specified where the compiler should look for units, libraries, object files. It also says where the output files should be stored. Multiple directories (except for the output directory) can be entered, separated by semicolons. The directories dialog is shown in figure (6.21).


Figure 6.21: The directories configuration dialog


The following directories can be specified:


EXE & PPU directories Specifies where the compiled units and executables will go. (-FE (see page 26) on the command line.)


Object directories Specifies where the compiler looks for external object files. (-Fo (see page 26) on the command line.)


Library directories Specifies where the compiler (more exactly, the linker) looks for external libraries. (-Fl (see page 26) on the command line.)


Include directories Specifies where the compiler will look for include files, included with the {$i } directive. (-Fi (see page 26) or -I (see page 26) on the command line.)


Unit directories Specifies where the compiler will look for compiled units. The compiler always looks first in the current directory, and also in some standard directories. (-Fu (see page 26) on the command line.)


6.11.3 The target operating system


The menu item "Compile|Target" allows specification of the target operating system for which the sources will be compiled. Changing the target doesn’t affect any compiler switches or directories. It does affect some defines defined by the compiler. The settings here correspond to the option on the command line -T (see page 30). A sample compilation target dialog is shown in figure (6.22): the actual dialog will show only those targets that the IDE actually supports.


The following targets can be set (the list depends on the platform for which the IDE was compiled):


Dos (go32v1) This switch will dissapear in time as this target is no longer being maintained.


Dos (go32v2) Compile for DOS, using version 2 of the Go32 extender.


FreeBSD Compile for FREEBSD.


Linux Compile for LINUX.


Figure 6.22: The compilation target dialog


OS/2 Compile for OS/2 (using the EMX extender).


Windows Compile for WINDOWS.


The currently selected target operating system is shown in the "Target" menu item in the "Compile" menu. Initially, this will be set to the operating system for which the IDE was compiled.


6.11.4 Compiler options


The menu "Options|Compiler" allow the settting of options that affect the compilers behaviour. When this menu item is chosen, a dialog pops up that displays several tabs.


There are six tabs:


Syntax Here options can be set that affect the various syntax aspects of the code. They correspond mostly to the -S option on the command line (section 5.1.5, page 31).


Code generation These options control the generated code; they are mostly concerned with the -C and -X command line options.


Verbose These set the verbosity of the compiler when compiling. The messages of the compiler are shown in the compiler messages window (can be called with F12).


Browser Options concerning the generated browser information. Browser information needs to be generated for the symbol browser to work.


Assembler Options concerning the reading of assembler blocks (-R on the command line) and the generated assembler (-A on the command line)


Processor Here the target processor can be selected.


On each tab page, there are two entry boxes: the first for Conditional defines and the second for additional compiler arguments. The symbols, and arguments, should be separated with semi-colons.


The syntax tab of the compiler options dialog is shown in figure (6.23).


Figure 6.23: The syntax options tab


In the syntax options dialog, the following options can be set:


Stop after first error when checked, the compiler stops after the first error. Normally the compiler continues compiling till a fatal error is reached. (-Se (see page 32) on the command line) Allow label and goto


Allow the use of label declarations and goto statements (-Sg (see page 32) on the command line).


Enable macros Allow the use of macros (-Sm (see page 32)).


Allow inline Allow the use of inlined functions (-Sc (see page 32) on the command line).


Include assertion code Include Assert statements in the code.


Load kylix compat. unit Load the Kylix compatibility unit.


Allow STATIC in objects Allow the Static modifier for object methods (-St (see page 33) on the command line)


C-like operators Allows the use of some extended operators such as +=, -= etc. (-Sc (see page 32) on the command line).


Compiler mode select the appropriate compiler mode:


Free Pascal Dialect The default Free Pascal compiler mode (FPC).


Object pascal extensions on Enables the use of classes and exceptions (-Sd (see page 32) on the command line).


Turbo pascal compatible Try to be more Turbo Pascal compatible (-So (see page 33) on the command line).


Delphi compatible Try to be more Delphi compatible (-Sd (see page 32) on the command line).


Macintosh Pascal dialect Try to be Macintosh pascal compatible.


The code generation tab of the compiler options dialog is shown in figure (6.24). Figure 6.24: The code generation options tab


In the code generation dialog, the following options can be set:


Run-time checks Controls what run-time checking code is generated. If such a check fails, a runtime


error is generated. The following checking code can be generated:


Range checking Checks the results of enumeration and subset type operations (-Cr (see page 28) command line option).


Stack checking Checks whether the stack limit is not reached (-Cs (see page 28) command line option).


I/O checking Checks the result of IO operations (-Ci (see page 28) command line option).


Integer overflow checking Checks the result of integer operations (-Co (see page 28) command line option).


Object method call checking Check the validity of the method pointer prior to calling it.


Position independent code Generate PIC code.


Create smartlinkable units Create smartlinkable units.


Optimizations What optimizations should be used when compiling:


Generate faster code Corresponds to the -OG command line option.


Generate smaller code Corresponds to the -Og command line option.


More information on these switches can be found in section 5.1.4, page 27. The processor tab of the compiler options dialog is shown in figure (6.25).


Figure 6.25: The processor selection tab


In the processor dialog, the target processor can be set. The compiler can use different optimizations for different processors.


The verbose tab of the compiler options dialog is shown in figure (6.26).


In this dialog, the following verbosity options can be set (on the command line: -v (see page 25)):


Warnings Generate warnings. Corresponds to -vw on the command line.


Notes Generate notes. Corresponds to -vn on the command line.


Hints Generate hints. Corresponds to -vh on the command line.


General info Generate general information. Corresponds to -vi on the command line.


User,tried info Generate information on used and tried files. Corresponds to -vut on the command line.


All Switch on full verbosity. Corresponds to -va on the command line.


Show all procedures if error If an error using overloaded procedure occurs, show all procedures. Corresponds to -vb on the command line.


The browser tab of the compiler options dialog is shown in figure (6.27). In this dialog, the browser options can be set:


No browser (default) No browser information is generated by the compiler.


Only global browser Browser information is generated for global symbols only, i.e. symbols defined not in a procedure or function (-b on the command line)


Local and global browser Browser information is generated for all symbols, i.e. also for symbols that are defined in procedures or functions (-bl on the command line)


Figure 6.26: The verbosity options tab


Remark: If no browser information is generated, the symbol browser of the IDE will not work.


The assembler tab of the compiler options dialog is shown in figure (6.28). The actual dialog may vary, as it depends on the target CPU the IDE was compiled for. In this dialog, the assembler reader and writer options can be set:


Assembler reader This permits setting the style of the assembler blocks in the sources:


AT&T assembler The assembler is written in AT&T style assembler (-Ratt on the command line).


Intel style assembler The assembler is written in Intel style assembler blocks (-Rintel on the command line).


remark that this option is global, but locally the assembler style can be changed with compiler directives.


Assembler info When writing assembler files, this option decides which extra information is written to the assembler file in comments:


List source The source lines are written to the assembler files together with the generated assembler (-al on the command line).


List register allocation The compiler’s internal register allocation/deallocation information is written to the assembler file (-ar on the command line).


List temp allocation The temporary register allocation/deallocation is written to the assembler file. (-at on the command line).


List node allocation The node allocation/deallocation is written to the assembler file. (-an on the command line).


use pipe with assembler use a pipe on unix systems when feeding the assembler code to an external assembler.


Figure 6.27: The browser options tab


The latter three of these options are mainly useful for debugging the compiler itself, it should rarely be necessary to use these.


Assembler output This option tells the compiler what assembler output should be generated.


Use default output This depends on the target.


Use GNU as Assemble using GNU as (-Aas on the command line).


Use NASM coff Produce NASM coff assembler (go32v2, -Anasmcoff on the command line)


Use NASM elf Produce NASM elf assembler (LINUX, -Anasmelf on the command line).


Use NASM obj Produce NASM obj assembler (-Anasmobj on the command line).


Use MASM Produce MASM (Microsoft assembler) assembler (-Amasm on the command line).


Use TASM Produce TASM (Turbo Assembler) assembler (-Atasm on the command line).


Use coff Write binary coff files directly using the internal assembler (go32v2, -Acoff on the command line).


Use pecoff Write binary pecoff files files directly using the internal writer. (Win32)


6.11.5 Linker options


The linker options can be set in the menu "Options|Linker". It permits the specification of how libraries and units are linked, and how the linker should be called. The linker options dialog is shown in figure (6.29).


The following options can be set:


Call linker after If this option is set then a script is written which calls the linker. This corresponds to the s option on the command line (-s (see page 30)).


Figure 6.28: The assembler options tab


Figure 6.29: The linker options dialog


Only link to static library Only use static libraries.


Preferred library type With this option, the type of library to be linked in can be set:


Target default This depends on the platform.


Dynamic libraries Tries to link in units in dynamic libraries. (option -XD on the command line.)


Static libraries Tries to link in units in static libraries. (option -XS on the command line.)


Smart libraries Tries to link in units in smart-linked libraries. (option -XX on the command


line.)


6.11.6 Memory sizes


The memory sizes dialog (reachable via "options|Memory sizes") permits the entry of the memory sizes for the project. The memory sizes dialog is shown in figure (6.30).


The following sizes can be entered:


Figure 6.30: The memory sizes dialog


Stack size Sets the size of the stack in bytes (option -Cs on the command line). This size may be ignored on some systems.


Heap size Sets the size of the heap in bytes; (option -Ch on the command line). Note that the heap grows dynamically as much as the OS allows.


6.11.7 Debug options


In the debug options dialog (reachable via "Options|Debugger"), some options for inclusion of debug information in the binary can be set; it is also possible to add additional compiler options in this dialog. The debug options dialog is shown in figure (6.31).


Figure 6.31: The debug options dialog


The following options can be set:


Debugging information tells the compiler which debug information should be compiled in. One of the following options can be chosen:


Strip all debug symbols from executable Will strip all debug and symbol information from the binary. (option -Xs on the command line).


Skip debug information generation Do not generate debug information at all.


Generate debug symbol information Include debug information in the binary (option -g on the command line). Please note that no debug information for units in the Run-Time Library will be included, unless a version of the RTL compiled with debug information is available. Only units specific to the current project will have debug information included.


Generate also backtrace line information Will compile with debug information, and will additionally include the lineinfo unit in the binary, so that in case of an error the backtrace will contain the file names and line numbers of procedures in the call-stack. (Option -gl on the command line.)


Generate valgrind compatible debug info Generate debug information that can be read with valgrind (a memory checking tool).


Profiling switches Tells the compiler whether or not profile code should be included in the binary.


No profile information Has no effect, as it is the default.


Generate Profile code for gprof If checked, profiling code is included in the binary (option -p on the command line).


Use another TTY for Debuggee An attempt will be made to redirect the output of the program being debugged to another window (terminal), whose file name should be entered here.


6.11.8 The switches mode


The IDE allows saving a set of compiler settings under a common name. It provides 3 names under which the switches can be saved:


Normal For normal (fast) compilation.


Debug For debugging; intended to set most debug switches on. Also useful for setting conditional defines that e.g. allow including some debug code.


Release For a compile of the program as it should be released, debug information should be off, the binary should be stripped, and optimizations should be used.


Selecting one of these modes will load the compiler options as they were saved the last time the selected mode was active, i.e. it doesn’t specifically set or unset options.


When setting and saving compiler options, be sure to select the correct switch mode first; it makes little sense to set debug options while the release switch is active. The switches mode dialog is shown in figure (6.32).


6.12 Customizing the IDE


The IDE is configurable over a wide range of parameters: colors can be changed, screen resolution. The configuration settings can be reached via the sub-menu Environment in the Options menu.


Figure 6.32: The switches mode dialog


Figure 6.33: The preferences dialog


6.12.1 Preferences


The preferences dialog is called by the menu item "Options|Environment|Preferences". The preferences dialog is shown in figure (6.33).


Video mode The drop down list at the top of the dialog allows selecting a video mode. The available video modes depend on the system on which the IDE is running.


Remark:


1. The video mode must be selected by pressing space or clicking on it. If the drop down list is opened while leaving the dialog, the new video mode will not be applied.


2. For the DOS version of the IDE, the following should be noted: When using VESA modes, the display refresh rate may be very low. On older graphics card (1998 and before), it is possible to use the UniVBE driver from SciTech(It can be downloaded from http://www.informatik.fh-muenchen.de/ ifw98223/vbehz.htm)

Desktop File Specifies where the desktop file is saved: the current directory, or the directory where the config file was found.


Auto save Here it is possible to set which files are saved when a program is run or when the IDE is exited:


Editor files The contents of all open edit windows will be saved.


Environment The current environment settings will be saved.


Desktop The desktop file with all desktop settings (open windows, history lists, breakpoints etc.) will be saved.


Options Some special behaviours of the IDE can be specified here:


Auto track source


Close on go to source When checked, the messages window is closed when the ’go to source line’ action is executed.


Change dir on open When a file is opened, the directory of that file is made the current working directory.


6.12.2 The desktop


The desktop preferences dialog allows to specify what elements of the desktop are saved across sessions, i.e. they are saved when the IDE is left, and they are again restored when the IDE is started the next time. They are saved in the file fp.dsk. The desktop preferences dialog is shown in figure (6.34).


Figure 6.34: The desktop preferences dialog


The following elements can be saved and restored across IDE sessions:


History lists Most entry boxes have a history list where previous entries are saved and can be selected. When this option is checked, these entries are saved in the desktop file. On by default.


Clipboard content When checked, the contents of the clipboard are also saved to disk. Off by default.


Watch expressions When checked, all watch expressions are saved in the desktop file. Off by default.


Breakpoints When checked, all breakpoints with their properties are saved in the desktop file. Off by default.


Open windows When checked, the list of files in open editor windows is saved in the desktop file, and the windows will be restored the next time the IDE is run. On by default.


Symbol information When checked, the information for the symbol browser is saved in the desktop file. Off by default.


CodeComplete wordlist When checked, the list of codecompletion words is saved. On by default.


CodeTemplates When checked, the defined code templates are saved. On by default.


Remark: The format of the desktop file changes between editor versions. So when installing a new version, it may be necessary to delete the fp.dsk files wherever the IDE searches for them.


6.12.3 The Editor


Several aspects of the editor window behaviour can be set in this dialog. The editor preferences dialog is shown in figure (6.35). Note that some of these options affect only newly opened windows, not already opened windows (e.g. Vertical Blocks, Highlight Column/Row).


Figure 6.35: The editor preferences dialog


The following elements can be set in the editor preferences dialog:

Create backup files Whenever an editor file is saved, a backup is made of the old file. On by default.


Insert mode Start with insert mode.


Auto indent mode Smart indenting is on. This means that pressing ENTER will position the cursor on the next line in the same column where text starts on the current line. On by default.


Use tab characters When the tab key is pressed, use a tab character. Normally, when the tab key is pressed, spaces are inserted. When this option is checked, tab characters will be inserted instead. Off by default.


Backspace unindents Pressing the BKSP key will unindent if the beginning of the text on the current line is reached, instead of deleting just the previous character. On by default.


Persistent blocks When a selection is made, and the cursor is moved, the selection is not destroyed,i.e. the selected block stays selected. On by default.

Syntax highlight Use syntax highlighting on the files that have an extension which appears in the list of highlight extensions. On by default.


Block insert cursor The insert cursor is a block instead of an underscore character. By default the overwrite cursor is a block. This option reverses that behaviour. Off by default.


Vertical blocks When selecting blocks spanning several lines, the selection doesn’t contain the entirety of the lines within the block; instead, it contains the lines as far as the column on which the cursor is located. Off by default.


Highlight column When checked, the current column (i.e. the column where the cursor is) is highlighted. Off by default.


Highlight row When checked, the current row (i.e. the row where the cursor is) is highlighted. Off by default.


Auto closing brackets When an opening bracket character is typed, the closing bracket is also inserted at once. Off by default.


Keep trailing spaces When saving a file, the spaces at the end of lines are stripped off. This option disables that behaviour; i.e. any trailing spaces are also saved to file. Off by default.


Codecomplete enabled Enable code completion. On by default.


Enable folds Enable code folding. Off by default.


Tab size The number of spaces that are inserted when the TAB key is pressed. The default value is 8.


Indent size The number of spaces a block is indented when calling the block indent function. The default value is 2.


Highlight extensions When syntax highlighting is on, the list of file masks entered here will be used to determine which files are highlighted. File masks should be separated with semicolon (;) characters. The default is *.pas;*.pp;*.inc.


File patterns needing tabs Some files (such as makefiles) need actual tab characters instead of spaces. Here a series of file masks can be entered to indicate files for which tab characters will always be used. Default is make*;make*.*.


Remark: These options will not be applied to already opened windows; only newly opened windows will have these options.


6.12.4 Keyboard & Mouse


The Keyboard & mouse options dialog is called by the menu item "Options|Environment|Keyboard & Mouse". It allows adjusting the behaviour of the keyboard and mouse as well as the sensitivity of the mouse. The keyboard and mouse options dialog is shown in figure (6.36).


Figure 6.36: The Keyboard & mouse options dialog


Keys for copy, cut and paste Set the keys to use for clipboard operations:


• CUA-91 convention (Shift+Del,Ctrl+Ins,Shift+Ins)


• Microsoft convention (Ctrl+X,Ctrl+C,Ctrl+V)

Mouse double click The slider can be used to adjust the double click speed. Fast means that the time between two clicks is very short; slow means that the time between two mouse clicks can be quite long.


Reverse mouse buttons the behaviour of the left and right mouse buttons can be swapped by by checking the checkbox; this is especially useful for left-handed people.


Ctrl+Right mouse button Assigns an action to a right mouse button click while holding the CTRL key pressed.


Alt+right mouse button Assigns an action to right mouse button click while holding the ALT key pressed.


The following actions can be assigned to CTRL-Right mouse button or ALT-right mouse button:


Nothing No action is associated to the event.


Topic search The keyword at the mouse cursor is searched in the help index.


Go to cursor The program is executed until the line where the mouse cursor is located.


Breakpoint Set a breakpoint at the mouse cursor position.


Evaluate Evaluate the value of the variable at the mouse cursor.


Add watch Add the variable at the mouse cursor to the watch list.


Browse symbol The symbol at the mouse cursor is displayed in the browser.


6.13 The help system


More information on how to handle the IDE, or about the use of various calls in the RTL, explanations regarding the syntax of a Pascal statement, can be found in the help system. The help system is activated by pressing F1.


6.13.1 Navigating in the help system


The help system contains hyperlinks; these are sensitive locations that lead to another topic in the help system. They are marked by a different color. The hyperlinks can be activated in one of two ways:


1. by directly clicking the one you want with the mouse, or


2. by using the TAB and SHIFT-TAB keys to move between the different hyperlinks of a page and then pressing the ENTER key to activate the one you want.

When SHIFT-F1 is pressed, the contents of the help system are displayed. To go back to the previous help topic, press ALT-F1. This also works if the help window isn’t displayed on the desktop; the help window will then be activated.


6.13.2 Working with help files


The IDE contains a help system which can display the following file formats:


TPH The help format for the Turbo Pascal help viewer.


INF The OS/2 help format.


NG The Norton Guide Help format.


HTML HTML files.


In future some more formats may be added. However, the above formats should cover already a wide spectrum of available help files.


Remark: Concerning the support for HTML files the following should be noted:


1. The HTML viewer of the help system is limited, it can only handle the most basic HTML files (graphics excluded), since it is only designed to display the Free Pascal help files.(but feel free to improve it and send patches to the Free Pascal development team... )


2. When the HTML help viewer encounters a graphics file, it will try and find a file with the same name but an extension of .ans; If this file is found, this will be interpreted as a file with ANSI escape sequences, and these will be used to display a text image. The displays of the IDE dialogs in the IDE help files are made in this way.


The menu item "Help|Files" permits help files to be added to, and deleted from, the list of files in the help table of contents. The help files dialog is displayed in figure (6.37).


Figure 6.37: The help files dialog


The dialog lists the files that will be presented in the table of contents window of the help system. Each entry has a small descriptive title and a filename next to it. The following actions are available when adding help files:


New Adds a new file. IDE will display a prompt, in which the location of the help file should be entered. If the added file is an HTML file, a dialog box will be displayed which asks for a title. This title will then be included in the contents of help.


Delete Deletes the currently highlighted file from the help system. It is not deleted from the hard disk; only the help system entry is removed.


Cancel Discards all changes and closes the dialog.


OK Saves the changes and closes the dialog.


The Free Pascal documentation in HTML format can be added to the IDE’s help system. This way the documentation can be viewed from within the IDE. If Free Pascal has been installed using the installer, the installer should have added the FPC documentation to the list of help files, if the documentation was installed as well.


6.13.3 The about dialog


The about dialog, reachable through ("Help|About...") shows some information about the IDE, such as the version number, the date it was built, what compiler and debugger it uses. When reporting bugs about the IDE, please use the information given by this dialog to identify the version of the IDE that was used.


It also displays some copyright information.


6.14 Keyboard shortcuts


A lot of keyboard shortcuts used by the IDE are compatible with WordStar and should be well known to Turbo Pascal users.


Below are the following tables:


1. In table (6.4) some shortcuts for handling the IDE windows and Help are listed.


2. In table (6.5) the shortcuts for compiling, running and debugging a program are presented.


3. In table (6.6) the navigation keys are described.


4. In table (6.7) the editing keys are listed.


5. In table (6.8) all block command shortcuts are listed.


6. In table (6.9) all selection-changing shortcuts are presented.


7. In table (6.10) some general shortcuts, which do not fit in the previous categories, are presented.


Table 6.4: General


Command Shortcut key Alternative


Help F1


Goto last help topic ALT-F1


Search word at cursor position in CTRL-F1


help Help index SHIFT-F1


Close active window ALT-F3


Zoom/Unzoom window F5


Move/Zoom active window CTRL-F5


Switch to next window F6


Switch to last window SHIFT-F6


Menu F10 Local menu ALT-F10


List of windows ALT-0


Active another window ALT-


Call grep utility SHIFT-F2


Exit IDE ALT-X


Table 6.5: Compiler


Command Shortcut key


Reset debugger/program CTRL-F2


Display call stack CTRL-F3


Run as far as the cursor F4


Switch to user screen ALT-F5


Trace into F7


Add watch CTRL-F7


Step over F8


Set breakpoint at current line CTRL-F8


Make F9


Run CTRL-F9


Compile the active source file ALT-F9


Message F11


Compiler messages F12


Chapter 7


Porting and portable code


7.1 Free Pascal compiler modes


The Free Pascal team tries to create a compiler that can compile as much as possible code produced for Turbo Pascal, Delphi or the Mac pascal compilers: this should make sure that porting code that was written for one of these compilers is as easy as possible.


At the same time, the Free Pascal developers have introduced a lot of extensions in the Object Pascal language. To reconcile these different goals, and to make sure that people can produce code which can still be compiled by the Turbo Pascal and Delphi compilers, the compiler has a concepts of ’compiler modes’. In a certain compiler mode, the compiler has certain functionalities switched on or off. This allows to introduce a compatibility mode in which only features supported by the original compiler are supported. Currently, 5 modes are supported:


FPC This is the original Free Pascal compiler mode: here all language constructs except classes, interfaces and exceptions are supported. Objects are supported in this mode. This is the default mode of the compiler.


OBJFPC This is the same mode as FPC mode, but it also includes classes, interfaces and exceptions.


TP Turbo Pascal compatibility mode. In this mode, the compiler tries to mimic the Turbo Pascal compiler as closely as possible. Obviously, only 32-bit or 64-bit code can be compiled.


DELPHI Delphi compatibility mode. In this mode, the compiler tries to resemble the Delphi compiler as best as it can: All Delphi 7 features are implemented. Features that were implemented in the .NET versions of Delphi are not implemented.


MACPAS the Mac Pascal compatibility mode. In this mode, the compiler attempts to allow all constructs that are implemented in Mac pascal. In particular, it attempts to compile the universal interfaces.


The compiler mode can be set on a per-unit basis: each unit can have its own compiler mode, and it is possible to use units which have been compiled in different modes intertwined. The mode can be set in one of 2 ways:


1. On the command line, with the -M switch.


2. In the source file, with the {$MODE } directive.

Both ways take the name of the mode as an argument. If the unit or program source file does not specify a mode, the mode specified on the command-line is used. If the source file specifies a mode, then it overrides the mode given on the command-line.


Thus compiling a unit with the -M switch as follows:


fpc -MOBJFPC myunit


is the same as having the following mode directive in the unit:


{$MODE OBJFPC}


Unit myunit;


The MODE directive should always be located before the uses clause of the unit interface or program uses clause, because setting the mode may result in the loading of an additional unit as the first unit to be loaded.


Note that the {$MODE } directive is a global directive, i.e. it is valid for the whole unit; Only one directive can be specified.


The mode has no influence on the availability of units: all available units can be used, independent of the mode that is used to compile the current unit or program.


7.2 Turbo Pascal


Free Pascal was originally designed to resemble Turbo Pascal as closely as possible. There are, of course, restrictions. Some of these are due to the fact that Turbo Pascal was developed for 16-bit architectures whereas Free Pascal is a 32-bit/64-bit compiler. Other restrictions result from the fact that Free Pascal works on more than one operating system.


In general we can say that if you keep your program code close to ANSI Pascal, you will have no problems porting from Turbo Pascal, or even Delphi, to Free Pascal. To a large extent, the constructs defined by Turbo Pascal are supported. This is even more so if you use the -Mtp or -MObjfpc switches.


In the following sections we will list the Turbo Pascal and Delphi constructs which are not supported in Free Pascal, and we will list in what ways Free Pascal extends Turbo Pascal.


7.2.1 Things that will not work


Here we give a list of things which are defined/allowed in Turbo Pascal, but which are not supported by Free Pascal. Where possible, we indicate the reason.


1. Duplicate case labels are permitted in Turbo Pascal, but not in Free Pascal. This is actually a bug in Turbo Pascal, and so support for it will not be implemented in Free Pascal.

2. In Turbo Pascal, parameter lists of previously defined functions and procedures did not have to match exactly. In Free Pascal, they must. The reason for this is the function overloading mechanism of Free Pascal. However, the -M (see page 31) option overcomes this restriction.

3. The Turbo Pascal variables MEM, MEMW, MEML and PORT for memory and port access are not available in the system unit. This is due to the operating system. Under DOS, the extender unit (GO32) implements the mem constuct. Under LINUX, the ports unit implements such a construct for the Ports variable.

4. Turbo Pascal allows you to create procedure and variable names using words that are not permitted in that role in Free Pascal. This is because there are certain words that are reserved in Free Pascal (and Delphi) that are not reserved in Turbo Pascal, such as: PROTECTED, PUBLIC, PUBLISHED, TRY, FINALLY, EXCEPT, RAISE. Using the -Mtp switch will solve this problem if you want to compile Turbo Pascal code that uses these words (chapter B, page 128 for a list of all reserved words).

5. The Turbo Pascal reserved words FAR, NEAR are ignored. This is because their purpose was limited to a 16-bit environment and Free Pascal is a 32-bit/64-bit compiler.

6. The Turbo Pascal INTERRUPT directive will work only on the Free Pascal DOS target. Other operating systems do not allow handling of interrupts by user programs.

7. By default the Free Pascal compiler uses AT&T assembler syntax. This is mainly because Free Pascal uses GNU as. However, other assembler forms are available. For more information, see the Programmer’s Guide.

8. Turbo Pascal’s Turbo Vision is available in Free Pascal under the name of FreeVision, which should be almost 100% compatible with Turbo Vision.

9. Turbo Pascal’s ’overlay’ unit is not available. It also isn’t necessary, since Free Pascal is a 32/64-bit compiler, so program size shouldn’t be an issue.

10. The command line parameters of the compiler are different.

11. Compiler switches and directives are mostly the same, but some extra exist.

12. Units are not binary compatible. That means that you cannot use a .tpu unit file, produced by Turbo Pascal, in a Free Pascal project.

13. The Free Pascal TextRec structure (for internal description of files) is not binary compatible with TP or Delphi.

14. Sets are by default 4 bytes in Free Pascal; this means that some typecasts which were possible in Turbo Pascal are no longer possible in Free Pascal. However, there is a switch to set the set size, see Programmer’s Guide for more information.

15. A file is opened for output only (using fmOutput) when it is opened with Rewrite. In order to be able to read from it, it should be reset with Reset.

16. Turbo Pascal destructors allowed parameters. This is not permitted in Free Pascal: by default, in Free Pascal, Destructors cannot have parameters. This restriction can be removed by using the -So switch.

17. Turbo Pascal permits more than one destructor for an object. In Free Pascal, there can be only one destructor. This restriction can also be removed by using the -So switch.

18. The order in which expressions are evaluated is not necessarily the same. In the following expression: a := g(2) + f(3); it is not guaranteed that g(2) will be evaluated before f(3).


19. In Free Pascal, you need to use the address @ operator when assigning procedural variables.


7.2.2 Things which are extra


Here we give a list of things which are possible in Free Pascal, but which didn’t exist in Turbo Pascal or Delphi.


1. Функции Free Pascal могут также возвращать сомплексные типы, такие как записи и массивы.


2. В языке Free Pascal Вы можете использовать возвращаемое значение функции как переменную.


Например:


function a: longint;


begin


a:=12;


while a>4 do


begin {...} end;


end;


The example above would work with TP, but the compiler would assume that the a>4 is a recursive call. If a recursive call is actually what is desired, you must append () after the function name:


function a : longint;


begin


a:=12; { this is the recursive call }


if a()>4 then


begin {...} end;


end;


3. In Free Pascal, there is partial support of Delphi constructs. (See the Programmer’s Guide for more information on this).


4. The Free Pascal exit call accepts a return value for functions.


function a : longint;


begin


a:=12;


if a>4 then


begin


exit(a*67); {function result upon exit is a*67 }


end;


end;


5. Free Pascal поддерживает перегрузку функций. Это означает, что Вы можете объявить несколько функций с одним и тем же именем, но с разными аргументами.


Например:


procedure DoSomething (a : longint); begin {...} end;


procedure DoSomething (a : real); begin {...} end;


Вы можете вызвать процедуру DoSomethink с аргументом типа Longint или Real. Однако при этом процедура или фукция должна быть предварительно объявлена и иметь одинаковые заголовки:


procedure x (v : longint); forward;


{...}


procedure x;{ This will overload the previously declared x} begin {...} end;


Такая конструкция вызовет ошибку при компиляции, т.к. компилятор не может найти процедуру procedure x (v : longint); Вместо этого Вы должны объявить процедуру x следующим образом:


procedure x (v : longint); { This correctly defines the previously declared x} begin {...} end;


The command line option -So (see page 33) disables overloading. When you use it, the above will compile, as in Turbo Pascal.


6. Operator overloading. Free Pascal allows operator overloading, e.g. you can define the ’+’ operator for matrices.


7. On FAT16 and FAT32 systems, long file names are supported.


7.2.3 Режим совместимости с Turbo Pascal


When you compile a program with the -Mtp switch, the compiler will attempt to mimic the Turbo Pascal compiler in the following ways:


• Assigning a procedural variable doesn’t require an @ operator. One of the differences between Turbo Pascal and Free Pascal is that the latter requires you to specify an address operator when assigning a value to a procedural variable. In Turbo Pascal compatibility mode, this is not required.


• Procedure overloading is disabled. If procedure overloading is disabled, the function header doesn’t need to repeat the function header.


• Forward defined procedures don’t need the full parameter list when they are defined. Due to the procedure overloading feature of Free Pascal, you must always specify the parameter list of a function when you define it, even when it was declared earlier with Forward. In Turbo Pascal compatibility mode, there is no function overloading; hence you can omit the parameter list:


Procedure a (L : Longint); Forward;


...


Procedure a ; { No need to repeat the (L : Longint) }


begin ... end;


• Recursive function calls are handled differently.


Consider the following example:


Function expr : Longint;


begin


...


Expr:=L:


Writeln (Expr);


...


end;


In Turbo Pascal compatibility mode, the function will be called recursively when the writeln statement is processed. In Free Pascal, the function result will be printed. In order to call the function recursively under Free Pascal, you need to implement it as follows :


Function expr : Longint;


begin


...


Expr:=L:


Writeln (Expr());


...


end;


• Any text after the final End. statement is ignored. Normally, this text is processed too.


• You cannot assign procedural variables to untyped pointers; so the following is invalid:


a: Procedure;


b: Pointer;


begin b := a; // Error will be generated.


• The @ operator is typed when applied on procedures.


• You cannot nest comments. Remark: The MemAvail and MaxAvail functions are no longer available in Free Pascal as of version 2.0. The reason for this incompatibility follows:


On modern operating systems,(The DOS extender GO32V2 falls under this definition of "modern" because it can use paged memory and run in multitasked environments.) the idea of "Available Free Memory" is not valid for an application. The reasons are:


1. One processor cycle after an application asked the OS how much memory is free, another application may have allocated everything.


2. It is not clear what "free memory" means: does it include swap memory, does it include disk cache memory (the disk cache can grow and shrink on modern OS’es), does it include memory allocated to other applications but which can be swapped out, etc.


Therefore, programs using MemAvail and MaxAvail functions should be rewritten so they no longer use these functions, because it does not make sense any more on modern OS’es. There are 3 possibilities:


1. Use exceptions to catch out-of-memory errors.


2. Set the global variable "ReturnNilIfGrowHeapFails" to True and check after each allocation whether the pointer is different from Nil.


3. Don’t care and declare a dummy function called MaxAvail which always returns High(LongInt) (or some other constant).


7.2.4 A note on long file names under DOS


Под управвлением операционной системы Windows 95 и выше, поддерживаются длинные имена файлов.


Moreover, Free Pascal supports the use of long filenames in the system unit and the Dos unit also for go32v2 executables. The system unit contains the boolean variable LFNsupport. If it is set to True then all system unit functions and Dos unit functions will use long file names if they are available. This should be so on WINDOWS 95 and 98, but not on WINDOWS NT or WINDOWS 2000. The system unit will check this by calling DOS function 71A0h and checking whether long filenames are supported on the C: drive.


It is possible to disable the long filename support by setting the LFNSupport variable to False; but in general it is recommended to compile programs that need long filenames as native WINDOWS applications.


7.3 Перенос кода Delphi


Porting Delphi code should be quite painless. The Delphi mode of the compiler tries to mimic Delphi as closely as possible. This mode can be enabled using the -Mdelphi command line switch, or by inserting the following code in the sources before the unit or program clause:


{$IFDEF FPC}


{$MODE DELPHI}


{$ENDIF FPC}


This ensures that the code will still compile with both Delphi and FPC.


Nevertheless, there are some things that will not work. Delphi compatibility is relatively complete up to Delphi 7. New constructs in higher versions of Delphi (notably, the versions that work with .NET) are not supported.


7.3.1 Missing language constructs


At the level of language compatibility, FPC is very compatible with Delphi: it can compile most of FreeCLX, the free Widget library that was shipped with Delphi 6, Delphi 7 and Kylix.


Currently, the only missing language constructs are:


1. Dynamic methods are actually the same as virtual.


2. Const for a parameter to a procedure does not necessarily mean that the variable or value is passed by reference.


3. Packages are not supported.


There are some inline assembler constructs which are not supported, and since Free Pascal is designed to be platform independent, it is quite unlikely that these constructs will be supported in the future.


Note that the -Mobjfpc mode switch is to a large degree Delphi compatible, but is more strict than Delphi. The most notable differences are:


1. Parameters or local variables of methods cannot have the same names as properties of the class in which they are implemented.


2. The address operator is needed when assigning procedural variables (or event handlers).


3. AnsiStrings are not switched on by default.


7.3.2 Missing calls / API incompatibilities


Delphi is heavily bound to Windows. Because of this, it introduced a lot of Windows-isms in the API (e.g. file searching and opening, loading libraries).


Free Pascal was designed to be portable, so things that are very Windows specific are missing, although the Free Pascal team tries to minimize this. The following are the main points that should be considered:


• By default, Free Pascal generates console applications. This means that you must explicitly enable the GUI application type for Windows: {$APPTYPE GUI}


• The Windows unit provides access to most of the core Win32 API. Some calls may have different parameter lists: instead of declaring a parameter as passed by reference (var), a pointer is used (as in C). For most cases, Free Pascal provides overloaded versions of such calls.


• Widestrings. Widestring management is not automatic in Free Pascal, since various platforms have different ways of dealing with widestring encodings and Multi-Byte Character Sets. FPC supports Widestrings, but may not use the same encoding as on Windows.


Note that in order to have correct widestring management, you need to include the cwstring unit on Unix/LINUX platforms: This unit initializes the widestring manager with the necessary callbacks which use the C library to implement all needed widestring functionality.


• Threads: At this moment, Free Pascal does not offer native thread management on all platforms; on Unix, linking to the C library is needed to provide thread management in an FPC application. This means that a cthreads unit must be included to enable threads.


• A much-quoted example is the SetLastOSError call. This is not supported, and will never be supported.


• Filename Case sensitivity: Pascal is a case-insensitive language, so the uses clause should also be case insensitive. Free Pascal ensures case insensitive filenames by also searching for a lowercase version of the file. Kylix does not do this, so this could create problems if two differently cased versions of the same filename are in the path.


• RTTI is NOT stored in the same way as for Delphi. The format is mostly compatible, but may differ. This should not be a problem if the API of the TypeInfo unit is used and no direct access to the RTTI information is attempted.


• By default, sets are of different size than in Delphi, but set size can be specified using directives or command line switches.


• Likewise, by default enumeration types are of different size than in Delphi. Here again, the size can be specified using directives or command line switches.


• In general, one should not make assumptions about the internal structure of complex types such as records, objects, classes and their associated structure. For example, the VMT table layout is different, the alignment of fields in a record may be different, etc.


• The same is true for basic types: on other processors the high and low bytes of a word or integer may not be at the same location as on an Intel processor (the endianness is different).


• Names of local variables and method arguments are not allowed to match the name of a property or field of the class: this is bad practise, as there can be confusion as to which of the two is meant.


7.3.3 Режим совместимости с Delphi


Switching on Dephi compatibility mode has the following effect:


1. Support for Classes, exceptions and threadvars is enabled.


2. The objpas is loaded as the first unit. This unit redefines some basic types: Integer is 32-bit for instance.


3. The address operator (@) is no longer needed to set event handlers (i.e. assign to procedural variables or properties).


4. Names of local variables and method parameters in classes can match the name of properties or field of the class.


5. The String keyword implies AnsiString by default.


6. Operator overloading is switched off.


7.3.4 Best practices for porting


When encountering differences in Delphi/FPC calls, the best thing to do is not to insert IFDEF statements whenever a difference is encountered, but to create a separate unit which is only used when compiling with FPC. The missing/incompatible calls can then be implemented in that unit. This will keep the code more readable and easier to maintain.


If a language construct difference is found, then the Free Pascal team should be contacted and a bug should be reported.


7.4 Writing portable code


Free Pascal is designed to be cross-platform. This means that the basic RTL units are usable on all platforms, and the compiler behaves the same on all platforms (as far as possible). The Object Pascal language is the same on all platforms. Nevertheless, FPC comes with a lot of units that are not portable, but provide access to all possibilities that a platform provides.


The following are some guidelines to consider when writing portable code:


• Avoid system-specific units. The system unit, the objects and classes units and the SysUtils unit are guaranteed to work on all systems. So is the DOS unit, but that is deprecated.


• Avoid direct hardware access. Limited, console-like hardware access is available for most platforms in the Video, Mouse and Keyboard units.


• Do not use hard-coded filename conventions. See below for more information on this.


• Make no assumptions on the internal representation of types. Various processors store information in different ways (’endianness’).


• If system-specific functionality is needed, it is best to separate this out in a single unit. Porting efforts will then be limited to re-implementing this unit for the new platform.


• Don’t use assembler, unless you have to. Assembler is processor specific. Some instructions will not work even on the same processor family.


• Do not assume that pointers and integers have the same size. They do on an Intel 32-bit processor, but not necessarily on other processors. The PtrInt type is an alias for the integer type that has the same size as a pointer. SizeInt is used for all size-related issues.


The system unit contains some constants which describe file access on a system:


AllFilesMask a file mask that will return all files in a directory. This is * on Unix-like platforms, and *.* on dos and windows like platforms.


LineEnding A character or string which describes the end-of-line marker used on the current platform. Commonly, this is one of #10, #13#10 or #13.


LFNSupport A boolean that indicates whether the system supports long filenames (i.e. is not limited to MS-DOS 8.3 filenames).


DirectorySeparator The character which acts as a separator between directory parts of a path.


DriveSeparator For systems that support drive letters, this is the character that is used to separate the drive indication from the path.


PathSeparator The character used to separate items in a list (notably, a PATH).


maxExitCode The maximum value for a process exitcode.


MaxPathLen The maximum length of a filename, including a path.


FileNameCaseSensitive A boolean that indicates whether filenames are handled case sensitively.


UnusedHandle A value used to indicate an unused/invalid file handle.


StdInputHandle The value of the standard input file handle. This is not always 0 (zero), as is commonly the case on Unices.


StdOutputHandle The value of the standard output file handle. This is not always 1, as is commonly the case on Unices.


StdErrorHandle The value of the standard diagnostics output file handle. This is not always 2, as is commonly the case on Unices.


CtrlZMarksEOF A boolean that indicates whether the #26 character marks the end of a file (an old MS-DOS convention).


To ease writing portable filesystem code, the Free Pascal file routines in the system unit and sysutils unit treat the common directory separator characters (/ and n) as equivalent. That means that if you use / on a WINDOWS system, it will be transformed to a backslash, and vice versa.


This feature is controlled by 2 (pre-initialized) variables in the system unit:


AllowDirectorySeparators A set of characters which, when used in filenames, are treated as directory separators. They are transformed to the DirectorySeparator character.


AllowDriveSeparators A set of characters which, when used in filenames, are treated as drive separator characters. They are transformed to the DriveSeparator character.


Раздел 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. Выводить только названия идентификаторов без их типов и описаний. По умолчанию типы выводятся.


Глава 9


Модули которые идут в комплекте с Free Pascal


Здесь мы перечислим модули которые идут в комплекте с дистрибутивом Free Pascal. С тех пор, как есть разница в поставке модулей под разные операционные системы, сначала мы опишем общие модули, затем опишем те, которые являются специфичными для каждой операционной системы


9.1 Стандартные модули


Следующие модули являются стандартными и подразумевается, что они должны быть портированы на все платформы которые поддерживает компилятор Free Pascal. Далее будет дано краткое описание каждого модуля.


charset (набор символов) Модуль, дающий возможность составлять таблици символов из доступных наборов.


cmem Использование этого модуля заменяет стандартный менеджер памяти Free Pascal на менеджер памяти библиотеки C.


crt Этот модуль аналогичен модулю с таким самим именем из набора компилятора Turbo Pascal. Он реализует вывод в консоль цветного текста, перемещение текстового курсора и чтение с клавиатуры.


dos Этот модуль предоставляет доступ к базовым операциям операционной системы. Он включает поиск файлов, доступ к переменным окружения, получение версии операционной системы, получение и установку системного времени. Стоит отметить, что некоторые из этих возможностей дублируются по функциональности в модуле sysutils.


dynlibs Обеспечивает кроссплатформенный доступ к загрузке динамических библиотек.


getopts Модуль который дает вам механизм разбора параметров командной строки(подобный GNU getopts). Он также поддерживает длинные имена параметров.


graph Этот модуль не рекомендован к использованию (больше всего будет исключен в следующих версиях компилятора). Этот модуль предоставляет базовые возможности рисования, такие как: рисование линий на экране, отображение текста и другие. Он предоставляет возможности аналогичные модулю graph, входящего в состав Turbo Pascal.


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


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


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


math Этот модуль предоставляет как общие математические операции(тригонометрические функции, логарифмы, и другие) так и более сложные(суммирование массивов, функции нормализации, и другие).


matrix Модуль предоставляет возможности манипуляциями матрицами.


mmx Модуль обеспечивает поддержку для mmx расширения в вашем коде.


mouse Предоставляет базовые возможности платформо-независимой работы с мышкой и поддерживает возможность написания собственный драйверов.


objects This unit provides the base object for standard Turbo Pascal objects. It also implements File and Memory stream objects, as well as sorted and non-sorted collections, and string streams.


objpas Он используется для совместимости с Delphi. Вы никогда не должны загружать этот модуль явно, он автоматически загружается если Вы используете режим Delphi совместимости.


printer Этот модуль предоставляет все что нужно для рудиментарного??? доступа к принтеру используя возможности I/O .


sockets Модуль дает программный доступ к сокетам и стеку TCP/IP.


strings Этот модуль предоставляет базовые возможности для работы со строками типа pchar, сопоставимый по возможностям со стандартной библиотекой С.


system Этот модуль доступен для всех поддерживаемых платформ. Он включает среди других, базовые файловые операции ввода/вывода, процедуры управления памятью, all compiler helper routines, and directory services routines.


strutils Предлагает много расширенных возможностей работы со строками.


dateutils Предлагает много расширенных возможностей для обработки и математических манипуляций над любыми значениями даты и времени.


sysutils Is an alternative implementation of the sysutils unit of Delphi. It includes file I/O access routines which takes care of file locking, date and string handling routines, file search, date and string conversion routines.


typinfo Предоставляет функции для доступа к информации о типах во время исполнения, подобно тому как это сделано в Delphi.


variants Обеспечивает базовую поддержку типа variant.


video Предоставляет базовые возможности платформо-независимой работы с экраном и поддерживает возможность написания собственный драйверов.


9.2 Под DOS


emu387 Этот модуль обеспечивает поддержку эмуляции сопроцессора.


go32 Этот модуль обеспечивает доступ к возможностям расширителя GO32 DOS.


ports This implements the various port[] constructs for low-level I/O.


9.3 Под Windows


wincrt This implements a console in a standard GUI window, contrary to the crt unit which is for the Windows console only.


Windows Этот модуль обеспечивает доступ ко всем Win32 API вызовам. Усилие было предпринято, чтобы убедиться, что он совместим с версией этого модуля для Delphi, таким образом код для Delphi легко переносится на Free Pascal.


opengl Обеспечивает доступ к низкоуровневым opengl функциям под WINDOWS.


winmouse Обеспечивает доступ к мышке под WINDOWS.


ole2 Обеспечивает доступ к OLE возможностям WINDOWS.


winsock Provides access to the WINDOWS sockets API Winsock.


Jedi windows header translations The units containing the Jedi translations of the Windows API headers is also distributed with Free Pascal. The names of these units start with jw, followed by the name of the particular API.


9.4 Under Linux and BSD-like platforms


baseunix Basic Unix operations, basically a subset of the POSIX specification. Using this unit should ensure portability across most unix systems.


clocale This unit initializes the internationalization settings in the sysutils unit with settings obtained through the C library.


cthreads This unit should be specified as the first or second unit in the uses clause of your program: it will use the Posix threads implementation to enable threads in your FPC program.


cwstring If widestring routines are used, then this unit should be inserted as one of the first units in the uses clause of your program: it will initialize the widestring manager in the system unit with routines that use C library functions to handle Widestring conversions and other widestring operations.


errors Returns a string describing an operating system error code.


Libc This is the interface to GLibc on a linux I386 system. It will not work for other platforms, and is in general provided for Kylix compatibility.


oldlinux This unit is deprecated. 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. It is recommended, however, that you use the baseunix, unixtype and unix units. They are more portable.


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 root or setuid root, and are a serious security risk on your system.


termio Terminal control routines, which are compatible to the C library routines.


unix Extended Unix operations.


unixtype All types used commonly on Unix platforms.


9.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 Presentation Manager (PM) functions (GUI).


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.


winsock Provides access to the (emulated) WINDOWS sockets API Winsock.


ports This implements the various port[] constructs for low-level I/O.


9.6 Unit availability


Standard unit availability for each of the supported platforms is given in the FAQ / Knowledge base.


Chapter 10


Debugging your programs


Free Pascal supports debug information for the GNU debugger gdb, or its derivatives Insight on win32 or ddd on LINUX. It can write 2 kinds of debug information:


stabs The old debug information format.


dwarf The new debug information format.


Both are understood by GDB.


This chapter briefly describes how to use this feature. It doesn’t attempt to describe completely the GNU debugger, however. For more information on the workings of the GNU debugger, see the GDB User Manual.


Free Pascal also suports gprof, the GNU profiler. See section 10.4 for more information on profiling.


10.1 Compiling your program with debugger support


First of all, you must be sure that the compiler is compiled with debugging support. Unfortunately, there is no way to check this at run time, except by trying to compile a program with debugging support.


To compile a program with debugging support, just specify the -g option on the command line, as follows:


fpc -g hello.pp


This will incorporate debugging information in the executable generated from your program source. You will notice that the size of the executable increases substantially because of this(A good reason not to include debug information in an executable you plan to distribute).


Note that the above will only incorporate debug information for the code that has been generated when compiling hello.pp. This means that if you used some units (the system unit, for instance) which were not compiled with debugging support, no debugging support will be available for the code in these units.


There are 2 solutions for this problem.


1. Recompile all units manually with the -g option.


2. Specify the ’build’ option (-B) when compiling with debugging support. This will recompile all units, and insert debugging information in each of the units.


The second option may have undesirable side effects. It may be that some units aren’t found, or compile incorrectly due to missing conditionals, etc.


If all went well, the executable now contains the necessary information with which you can debug it using GNU gdb.


10.2 Using gdb to debug your program


To use gdb to debug your program, you can start the debugger, and give it as an option the full name of your program:


gdb hello


Or, under DOS:


gdb hello.exe


This starts the debugger, and the debugger immediately loads your program into memory, but it does not run the program yet. Instead, you are presented with the following (more or less) message, followed by the gdb prompt ’(gdb)’:


GNU gdb 6.6.50.20070726-cvs


Copyright (C) 2007 Free Software Foundation, Inc.


GDB is free software, covered by the GNU General Public License, and you are welcome to change it and/or distribute copies of it under certain conditions.


Type "show copying" to see the conditions.


There is absolutely no warranty for GDB. Type "show warranty" for details.


This GDB was configured as "x86_64-suse-linux". (gdb)


The actual prompt will vary depending on your operating system and installed version of gdb, of course.


To start the program you can use the run command. You can optionally specify command line parameters, which will then be fed to your program, for example:


(gdb) run -option -anotheroption needed_argument


If your program runs without problems, gdb will inform you of this, and return the exit code of your program. If the exit code was zero, then the message ’Program exited normally’ is displayed.


If something went wrong (a segmentation fault or such), gdb will stop the execution of your program, and inform you of this with an appropriate message. You can then use the other gdb commands to see what happened. Alternatively, you can instruct gdb to stop at a certain point in your program, with the break command.


Here is a short list of gdb commands, which you are likely to need when debugging your program:


quit Exit the debugger.


kill Stop a running program.


help Give help on all gdb commands.


file Load a new program into the debugger.


directory Add a new directory to the search path for source files.


Remark: My copy of gdb needs ’.’ to be added explicitly to the search path, otherwise it doesn’t find the sources.


list List the program sources in chunks of 10 lines. As an option you can specify a line number or function name.


break Set a breakpoint at a specified line or function.


awatch Set a watch-point for an expression. A watch-point stops execution of your program whenever the value of an expression is either read or written.


In appendix E a sample init file for gdb is presented. It produces good results when debugging Free Pascal programs.


For more information, refer to the gdb User Manual, or use the ’help’ function in gdb.


The text mode IDE and Lazarus both use GDB as a debugging backend. It may be preferable to use that, as they hide much of the details of the debugger in an easy-to-use user interface.


10.3 Caveats when debugging with gdb


There are some peculiarities of Free Pascal which you should be aware of when using gdb. We list the main ones here:


1. Free Pascal generates information for GDB in uppercase letters. This is a consequence of the fact that Pascal is a case insensitive language. So, when referring to a variable or function, you need to make its name all uppercase. As an example, if you want to watch the value of a loop variable count, you should type


watch COUNT


Or if you want to stop when a certain function (e.g MyFunction) is called, type


break MYFUNCTION


2. gdb does not know sets.


3. gdb doesn’t know strings. Strings are represented in gdb as records with a length field and an array of char containing the string.


You can also use the following user function to print strings:


define pst


set $pos=&$arg0


set $strlen = {byte}$pos


print {char}&$arg0.st@($strlen+1)


end


document pst


Print out a Pascal string


end


If you insert it in your gdb.ini file, you can look at a string with this function. There is a sample gdb.ini in appendix E.


4. Objects are difficult to handle, mainly because gdb is oriented towards C and C++. The workaround implemented in Free Pascal is that object methods are represented as functions, with an extra parameter this (all lowercase!). The name of this function is a concatenation of the object type and the function name, separated by two underscore characters. For example, the method TPoint.Draw would be converted to TPOINT__DRAW, and you could stop at it by using:


break TPOINT__DRAW


5. Global overloaded functions confuse gdb because they have the same name. Thus you cannot set a breakpoint at an overloaded function, unless you know its line number, in which case you can set a breakpoint at the starting line number of the function.


10.4 Support for gprof, the GNU profiler


You can compile your programs with profiling support. For this, you just have to use the compiler switch -pg. The compiler will insert the necessary stuff for profiling.


When you have done this, you can run your program as you would normally run it:


yourexe


Where yourexe is the name of your executable.


When your program finishes, a file called gmon.out is generated. Then you can start the profiler to see the output. You can benefit from redirecting the output to a file, because it could be quite a lot:


gprof yourexe > profile.log


Hint: you can use the -flat option to reduce the amount of output of gprof. It will then only output the information about the timings.


For more information on the GNU profiler gprof, see its manual.


10.5 Detecting heap memory leaks


Free Pascal has a built in mechanism to detect memory leaks. There is a plug-in unit for the memory manager that analyses the memory allocation/deallocation and prints a memory usage report after the program exits.


The unit that does this is called heaptrc. If you want to use it, you should include it as the first unit in your uses clause. Alternatively, you can supply the -gh switch to the compiler, and it will include the unit automatically for you.


After the program exits, you will get a report looking like this:


Marked memory at 0040FA50 invalid


Wrong size : 128 allocated 64 freed


0x00408708


0x0040CB49


0x0040C481


Call trace for block 0x0040FA50 size 128


0x0040CB3D


0x0040C481


The output of the heaptrc unit is customizable by setting some variables. Output can also be customized using environment variables.


You can find more information about the usage of the heaptrc unit in the Unit Reference.


10.6 Line numbers in run-time error backtraces


Normally, when a run-time error occurs, you are presented with a list of addresses that represent the call stack backtrace, i.e. the addresses of all procedures that were invoked when the run-time error occurred.


This list is not very informative, so there exists a unit that generates the file names and line numbers of the called procedures using the addresses of the stack backtrace. This unit is called lineinfo.


You can use this unit by giving the -gl option to the compiler. The unit will be automatically included. It is also possible to use the unit explicitly in your uses clause, but you must make sure that you compile your program with debug info.


Here is an example program:


program testline;


procedure generateerror255;


begin


runerror(255);


end;


procedure generateanerror;


begin


generateerror255;


end;


begin


generateanerror;


end.


When compiled with -gl, the following output is generated:


Runtime error 255 at 0x0040BDE5


0x0040BDE5 GENERATEERROR255, line 6 of testline.pp


0x0040BDF0 GENERATEANERROR, line 13 of testline.pp


0x0040BE0C main, line 17 of testline.pp


0x0040B7B1


This is more understandable than the normal message. Make sure that all units you use are compiled with debug info, because if they are not, no line number and filename can be found.


10.7 Combining heaptrc and lineinfo


If you combine the lineinfo and the heaptrc information, then the output of the heaptrc unit will contain the names of the files and line numbers of the procedures that occur in the stack backtrace.


In such a case, the output will look something like this:


Marked memory at 00410DA0 invalid


Wrong size : 128 allocated 64 freed


0x004094B8


0x0040D8F9 main, line 25 of heapex.pp


0x0040D231


Call trace for block 0x00410DA0 size 128


0x0040D8ED main, line 23 of heapex.pp


0x0040D231


If lines without filename / line number occur, this means there is a unit which has no debug info included (in the above case, the getmem call itself).


Приложение А


Список параметров командной строки в алфавитном порядке


Следующий список всех параметров командной строки был сгенерирован компилятором:


Free Pascal компилятор версии 2.4.0rc1 [2009/11/06] для x86_64


Copyright (c) 1993-2009 by Florian Klaempfl


/usr/local/lib/fpc/2.4.0/ppcx64 [опции]




оставить комментарий
страница3/10
Дата18.09.2011
Размер1,33 Mb.
ТипРуководство пользователя, Образовательные материалы
Добавить документ в свой блог или на сайт

страницы: 1   2   3   4   5   6   7   8   9   10
Ваша оценка этого документа будет первой.
Ваша оценка:
Разместите кнопку на своём сайте или блоге:
rudocs.exdat.com

Загрузка...
База данных защищена авторским правом ©exdat 2000-2017
При копировании материала укажите ссылку
обратиться к администрации
Анализ
Справочники
Сценарии
Рефераты
Курсовые работы
Авторефераты
Программы
Методички
Документы
Понятия

опубликовать
Документы

наверх