Приложение D

Настоящая глава описывает порядок использования компилятора TADS 2, а также доступные опции и параметры компиляции.

Компилятор TADS

Компилятор TADS (как, впрочем, и любой другой компилятор) - это программа, которая считывает ваш исходный код, проверяет корректность его синтаксиса и преобразует его в двоичный формат, с которым может работать программа-интерпретатор TADS. Как правило, конечный файл игры в двоичном формате значительно меньше по объему, чем исходные файлы. Символьные последовательности исходного кода TADS преобразуются в последовательности байтов, напоминающих машинный язык, а строковые значения сжимаются с использованием алгоритма кодирования с переменной длиной ключа в байтах (что, помимо уменьшения объема, сужает возможности игроков по "нечестному" прохождению игры - путем чтения выводимых сообщений и описаний в файле игры), а объекты преобразуются в компактные структуры данных.

В данном приложении Руководства описываются опции и параметры, которые можно использовать для управления компилятором TADS. Обратите внимание, что здесь приведен обобщенный формат команд, и для отдельных операционных систем могут действовать слегка отличающиеся соглашения; эти особенности обычно описаны в сопроводительной документации к компилятору под конкретную операционную систему. Кроме того, для запуска компилятора от вас могут потребоваться некие минимальные действия по конфигурации системы (например, прописывание пути к исполняемому файлу компилятора в системной переменной PATH или аналогичной).

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

Кроме того, версия компилятора для MacOS не добавляет расширение по умолчанию к исходным файлам. В ранних версиях компилятор автоматически добавлял к названию исходного файла расширение ".t", если в имени файла не было точек. Хотя добавление расширения по умолчанию может быть удобным для некоторых платформ (все догадались, о какой платформе идет речь;) - примечание переводчика), поскольку избавляет от необходимости вводить расширение файла вручную, для "Маков" это нежелательно, поскольку пользователь выбирает необходимый файл мышкой; при этом полное имя файла определяется автоматически, и расширение попросту не нужно.

Весь последующий материал посвящен в основном компилятору, запускаемому из командной строки Windows. Компиляцию можно осуществлять также из графического отладчика TADS Workbench, при этом набор доступных опций остается в принципе тем же. Особенностям компиляции из TADS Workbench будет посвящен отдельный раздел.

Запуск компилятора

Для запуска компилятора TADS из командной строки необходимо набрать имя исполняемого файла компилятора (tc32, для некоторых версий оно может звучать как tc или tadsc) и имя компилируемого файла игры. Например:

  tc32 primer 

При таком вызове на основе исходного кода из файла primer.t (по умолчанию компилятор автоматически добавляет расширение .t к имени компилируемого файла) будет создан файл игры primer.gam.

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

Опции компилятора

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

  tc32 опции имя_файла 

Например, чтобы скомпилировать файл primer.t с включением в файл игры отладочной информации, можно ввести следующую команду:

  tc32 -ds primer 

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

  tc32 -ic:\tads -od:\primer primer
  tc32 -i c:\tads -o d:\primer primer 

Единственное исключение - опции памяти, для которых необходимо указывать тип выделяемой памяти непосредственно за опцией -m; в то же время размер памяти может отделяться пробелом. Следующие две команды будут корректны:

  tc32 -mh5000 primer 
  tc32 -mh 5000 primer

Ниже приведен полный список распознаваемых компилятором опций. Для получения краткого списка (на английском, правда, языке) достаточно ввести в командной строке tc32 без параметров. Обратите внимание, что опции компилятора в общем случае чувствительны к регистру символов.

Для опций, служащих "переключателями" режимов компиляции, действует следующее общее соглашение: знак "+" после опции означает, что режим включается, "-" - отключаетcя, а отсутствие знака означает переключение (или "обращение") предшествующей установки.

-C	Данная опция позволяет включать и отключать использование операторов в стиле C. По умолчанию значение этой опции -C-, т. е. используются стандартные операторы TADS. Если указать компилятору -C+, то оператором присваивания будет считаться "=", а оператором сравнения на равенство - "==" (т. е. так, как это принято в языке C).
-case	Компилятор позволяет отключать чувствительность к регистру символов. Если вы не хотите, чтобы компилятор различал верхний и нижний регистр символов (например, в идентификаторах и т. д.), вы можете указать опцию -case-. Значение этой опции по умолчанию -case+, т. е. регистр символов имеет значение; скажем, deepverb и deepVerb в этом случае будут восприниматься как разные идентификаторы. Обратите внимание, что с компиляцией стандартной библиотеки advr.t проблем не возникнет в любом режиме. С одной стороны, все идентификаторы в ней определены с уникальным набором символов, и не используют для различения их регистр (т. е. там не встречается пар идентификаторов типа Ident и ident - если бы такое было, то при компиляции с отключенной чувствительностью к регистру произошел бы "конфликт интересов"). С другой же стороны, один и тот же идентификатор во всех случаях задан с одинаковым набором заглавных и строчных букв - в противном случае возникали бы проблемы при включении чувствительности к регистру.
-ctab файл	Позволяет задать файл с таблицей символов (т. н. character mapping file, с расширением .TCP), который будет определять, как будут интерпретироваться символы расширенного набора ASCII (с кодом более 127) при исполнении программы. Подробнее см. в соответствующем разделе документации.
-D символ=значение	Определяет символ препроцессинга с указанным значением. Если знак равенства и значение не указаны, символ определяется равным 1. Определенные таким образом символы препроцессинга полностью аналогичны символам, определенным при помощи инструкции #define в теле самой программы.
-ds	Включить в файл игры отладочную информацию. Эта информация используется утилитой отладки - TADS Debugger - для трассировки выполнения программы и "привязки" исполняемого кода к исходному. Следует оговориться, что сама утилита TADS Debugger, можно сказать, морально устарела - в настоящее время подавляющее большинство пользователей (особенно русскоязычных) используют отладчик HTML-TADS, встроенный в TADS Workbench. Для него отладочная информация имеет другой формат и генерируется по опции -ds2 (см. ниже). Поэтому данная опция имеет, скорее, исторический интерес; единственный вариант, когда она может быть полезна - если используется ОС, отличная от Windows.
-ds2	Включить в файл отладочную информацию в новом формате, с которым работает отладчик HTML-TADS (входящий в состав TADS Workbench), начиная с версии TADS 2.5.0. Если по какой-либо причине вы используете более старую версию платформы, либо работаете в другой операционной системе (DOS (ха!), Nix-платформы, Mac), то следует использовать опцию -ds, рассмотренную абзацем выше. Обратите внимание, что включение отладочной информации (в любом формате) увеличивает размер конечного файла; кроме того, в отладочном режиме выводимый игрой текст записывается в файл в незашифрованном виде (со всеми вытекающими последствиями). В связи с этим настоятельно рекомендуется отключать отладочный режим при компиляции окончательной редакции игры.
-e имя_файла	При указании данной опции компилятор будет записывать все возникающие сообщения об ошибках в файл с именем имя_файла. При этом все сообщения будут также параллельно выводиться на экран обычным образом. Если файл не существует, он будет создан, а если существует - перезаписан.
-Fsigra.lis igra.t	При задании этой опции компилятор, как обычно, создает файл igra.gam, но параллельно записывает все строковые значения из исходного файла в файл igra.lis. Если файл с таким именем уже существует, он перезаписывается. Другими словами, при помощи этой опции компилятор может вычленить весь текст, используемый в игре. Это может быть весьма полезно для автоматизированной корректуры текста, поскольку позволяет отделить текст от исходного кода.
-fv тип	Устанавливает формат файла .GAM. Параметр тип может принимать значения a (так называемый формат "A", использовавшийся в TADS вплоть до версии 2.1), b (формат "B", используемый, начиная с версии 2.1.0), c (формат "C", впервые введенный в версии 2.2 и используемый по настоящее время), а также *, что означает использование наиболее современного на данный момент формата. Значение этой опции по умолчанию - -fv*, что в настоящее время соответствует формату "C". Использование других форматов не рекомендуется, если на это не имеется каких-то веских специфических причин. Любая более поздняя версия интерпретатора TADS способна прочитать файлы формата, использовавшегося более старыми версиями. В то же время более старые версии интерпретатора не смогут прочитать файлы форматов, возникших после их появления. Обратите внимание, что в старых версиях TADS периодически вносились влияющие на совместимость изменения в формат файла, при этом программа-интерпретатор не всегда могла их обнаружить. В связи с этим использование разных версий компилятора и интерпретатора может быть небезопасным с точки зрения стабильности работы программы (еще раз повторим - это касается только версий TADS более ранних, чем 2.1). Одним из важных нововведений формата "B" по сравнению с предыдущим стала намного лучшая "сжимаемость" файла игры программами-архиваторами. Изменения, внесенные в формат "C", обеспечивают функционирование флага-модификатора disambigDobjFirst. При компиляции в файл более раннего формата вы не сможете использовать этот флаг.
-iпуть	Добавляет путь в список путей для поиска включаемых в исходный код файлов. Если вы используете для включения файла в исходный код директиву #include, заключая имя включаемого файла в угловые скобки (< и >), то компилятор будет искать данный файл в списке каталогов, заданных опцией -i в том порядке, в котором они в ней перечислены. Обратите внимание, что некоторые из предыдущих версий TADS требовали завершать имя пути символом разделения каталогов, принятом в данной операционной системе (для DOS и Windows это обратный слэш); в настоящее время этого более не требуется, однако использование такого символа не будет приводить к ошибкам.
-lимя_файла	Загружает предкомпилированный файл. Этот файл необходимо создать заранее с использованием опции -w. Таким образом можно ускорить компиляцию программы, заранее скомпилировав файлы, которые вы не предполагаете менять (например, внешние библиотеки). Загрузка файла в двоичном формате происходит значительно быстрее, чем компиляция его из исходного кода (хотя при современных вычислительных мощностях разница и некритична). Обратите внимание, что непосредственно при помощи опции -l можно загрузить только один предкомпилированный файл. Однако это ограничение легко обходится: для этого достаточно создать файл, целиком состоящий из директив #include с указанием всех файлов, которые требуется предкомпилировать в одну общую двоичную библиотеку. Кроме того, файлы могут включаться при компиляции только один раз; если компилятор встречает вторую директиву #include со ссылкой на уже включенный ранее файл, он ее игнорирует. Это повышает удобство использования предкомпилированных файлов, поскольку не требует от автора правки исходного кода - все директивы #include можно оставить без изменений. При использовании предкомпилированной библиотеки те из них, которые в нее входят, будут проигнорированы; если предкомпиляция не используется, все встречающиеся в этих директивах исходные файлы будут скомпилированы обычным образом.
-mтип_объектов объем	Выделяет заданный объем памяти под указанный тип_объектов (в данном случае имеются в виду не объекты, определенные автором в игровой программе, а внутренние параметры компиляции). По умолчанию компилятор выделяет под те или иные нужды области памяти определенного размера. Соответственно, если компьютер не оборудован необходимым количеством памяти, либо если игровой программе потребуется памяти больше, чем выделено, объемы выделяемой памяти необходимо будет скорректировать. Если субопция после -m не указана, то память заданного объема будет выделена под виртуальный объектный кэш. Кроме того, доступны следующие субопции: g - размер таблицы безусловных переходов goto h - размер кучи l - размер таблицы локальных переменных p - размер пула узлов грамматического разбора s - размер стека Чтобы определить принятые по умолчанию объемы выделяемой под разные типы объектов памяти для вашей версии компилятора, запустите его с ключом -m?. Смысл отдельных субопций выделения памяти будет разъяснен далее.
-oимя_файла	Назначает в качестве файла, в который будет записана скомпилированная игра, файл с именем имя_файла. Если имя_файла не содержит расширения, по умолчанию будет назначено расширение .gam. Обратите внимание, что при указании опции -o- выходной файл создаваться не будет.
-p	Указывает компилятору, что перед завершением работы необходимо ждать нажатия клавиши. Данная опция очень полезна, например, в том случае, если версия компилятора для командной строки запускается в операционной системе Windows с рабочего стола. По умолчанию Windows настроена так, что окна консольных приложений закрываются сразу после завершения работы, и пользователь зачастую не может увидеть выведенные компилятором сообщения об ошибках. Описываемая опция позволяет обойти данное ограничение, не углубляясь в дебри системных настроек. Обратите внимание, что для GUI-версий компилятора (точнее, TADS Workbench) данная опция неактуальна, поскольку работа приложения всегда будет завершаться по команде пользователя. Примечание переводчика: до версии 2.5.11 эта опция не работала.
-s	При включении данной опции после компиляции игры будут выводиться статистические данные об использовании памяти.
-t	Служит для включения и отключения своппинга - выгрузки части данных в специальный файл подкачки. Обратите внимание, что даже при включении данной опции файл подкачки будет создаваться только в случае необходимости - т. е. только тогда, когда кэш будет заполнен целиком и разместить в нем данные будет невозможно.
-tf имя_файла	Использовать для подкачки файл с именем имя_файла. По умолчанию используется файл TADSSWAP.DAT в текущем каталоге. Например, при использовании виртуального диска, размещенного в оперативной памяти, имеет смысл разместить файл подкачки на этом диске, подняв таким образом производительность.
-ts объем	Ограничивает размер файла подкачки объемом байт. Использование данной опции имеет смысл, если место на вашем диске ограничено (хотя, честно говоря, на современных компьютерах и с учетом относительной компактности текстовых игр по сравнению с другими приложениями этот размер вряд ли будет критичным).
-U символ	Отменяет определение символа препроцессинга. Отмена определения символа из командной строки компилятора полностью аналогична таковой, выполненной при помощи инструкции #undefine в самом начале исходного кода программы.
-v уровень	Устанавливает уровень подробности выводимых предупреждающих сообщений. Всего существует три уровня: 0 (принятый по умолчанию "минимальный" уровень; подавление вывода чисто информационных сообщений и таких предупреждений, которые в большинстве случаев не свидетельствуют о наличии какой-либо проблемы); 1 (подавление вывода чисто информационных сообщений, предупреждения выводятся в любом случае); и 2 (наиболее подробный; выводятся все сообщения и предупреждения).
-v-abin	Отключает вывод предупреждающего сообщения "operator x interpreted as unary in list." ("оператор & в списке воспринят как унарный", TADS-357)." Вместо x может стоять знак амперсанда, плюс или минус. Подробнее данная проблема рассмотрена здесь.
-wимя_файла	Записывает предкомпилированную версию исходного кода в файл с именем имя_файла. Никаких расширений по умолчанию к имени файла не добавляется. При указании этой опции опция -o всегда будет игнорироваться, так как файл игры создаваться не будет. Файлы, создаваемые при помощи опции -w, предназначены для того, чтобы подгружаться в ходе компиляции посредством опции -l, за счет чего сокращается время компиляции.
-Za	При включении этой опции (что соответствует режиму по умолчанию) TADS проверяет соответствие количества передаваемых аргументов при вызове функции. Такая проверка появилась, начиная со 2-й версии TADS; в TADS 1 ее не было, вследствие чего там допускалось расхождение между количеством формальных аргументов, указанным в определении функции, и реальным количеством аргументов, передаваемом при вызове. В TADS 2 такой вызов приведет к ошибке периода исполнения. Использование опции -Za при компиляции позволяет подавлять вывод таких сообщений, что во многих случаях не приведет к каким-либо отрицательным последствиям.
-1	Включает все опции совместимости с 1-й версией TADS. Эти опции позволят вам скомпилировать древнюю игру на TADS 1, если вам когда-нибудь попадет ее исходный код.
-1a	Аналог опции -Za: отключает контроль за количеством передаваемых аргументов в процессе выполнения программы.
-1dключевое_слово	Заменяет ключевое слово do (используемое в конструкции do-while) на другое ключевое_слово по вашему выбору (состоящее, естественно, из латинских букв). Если вы модифицируете старую игру на TADS 1, использующую do в качестве идентификатора, но при этом хотите сохранить возможность использования современных языковых конструкций TADS 2 (таких как switch и for), то вы сможете задать при помощи данной опции новое ключевое слово, которое можно будет использовать вместо do. Например, при указании -1d DO можно будет использовать do в качестве имени переменной, а циклы do-while описывать, применяя ключевое слово DO. При этом (в отличие от применения опции -1k) сохраняется возможность использования всех управляющих конструкций, характерных для второй версии TADS (switch, for и т. д.).
-1e	Игнорирование точки с запятой между закрывающей фигурной скобкой и инструкцией else. В 1-й версии TADS такая конструкция допускалась, хотя синтаксис языка TADS ее и не предусматривал. Во второй версии эта конструкция по умолчанию запрещена; опция -1e снимает это запрещение, позволяя скомпилировать старый код.
-1k	Отключает использование инструкций, введенных во второй версии: for, do, switch, case, default и goto. При использовании опции -1k все эти слова можно использовать в качестве идентификаторов. Разумеется, использование их по прямому назначению становится невозможным, поэтому данную опцию следует использовать только для обеспечения совместимости старого кода.

Выделение памяти

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

Компилятор проводит проверку корректности заданных в различных опциях (в частности, -mg, -mp, -ml, -ms и -mh) объемов выделяемой памяти. Указанные значения должны лежать в определенных пределах, соблюдение которых строго контролируется. В более ранних версиях компилятора установка некорректных параметров могла приводить к непредсказуемым результатам.

Размер таблицы меток для goto (-mg)

Данный параметр ограничивает размер внутренней таблицы, используемой для хранения меток для оператора goto внутри функции. Скорее всего, вам никогда не понадобится его менять - в особенности если вы не используете goto в своих программах.

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

Значение этого параметра по умолчанию - обычно 1024 или 8192 байт (очевидно, для разных версий компилятора - примечание переводчика). Максимальное значение может составлять 64 Кб, но устанавливать его таким большим никогда не потребуется, если только вы не являетесь маниакальным поклонником оператора безусловного перехода.

Размер таблицы локальных переменных (-ml)

Данная внутренняя таблица используется компиилятором для хранения определений локальных переменных. Как и таблица меток для goto, она создается заново для каждой функции, и поэтому ее минимально необходимый размер определяется объемом самой богатой переменными функции, а не размером программы.

По умолчанию под эту таблицу выделяется 4096 или 16384 байт. Обратите внимание, что значения размеров таблицы локальных переменных и пула узлов грамматического разбора взаимосвязаны - суммарный объем памяти, выделяемый по этим двум опциям, не должен превышать 64 Кб.

Размер пула узлов грамматического разбора (-mp)

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

Данная таблица используется компилятором для временного хранения внутренних структур данных, используемых при разборе выражений. Как правило, необходимый объем памяти напрямую зависит от сложности выражений (в том числе наличия/количества таких их элементов, как объявление переменных, наличие условных операторов, операторов цикла и т. п.). Кроме того, для некоторых операторов необходимо отслеживать сразу несколько выражений, что приводит к росту сложности в геометрической прогрессии (таковы, например, операторы for и вложенные операторы switch).

Значение по умолчанию для этого параметра - обычно 6144 или 24576 байт. Последнего значения хватит для компиляции даже огромных игр (примечание переводчика: увы, это не совсем так - проверено на практике. Необходимо еще раз подчеркнуть, что минимальное требуемое значение для этого параметра определяется не размером всей игры, а, говоря упрощенно, "габаритами" самой большой сущности в ней, т. е. при использовании "развесистых" функций и объектов вполне можно выйти за этот предел. Если увеличение памяти по каким-то причинам не помогает, можно локализовать такие "объекты-переростки" и разбить их на ряд более мелких). Необходимо еще раз подчеркнуть, что сумма объемов памяти под пул узлов разбора и таблицу локальных переменных не должна превышать 64 Кб, т. е. когда вы увеличиваете размер для одного параметра, то может оказаться, что для второго его необходимо уменьшить.

Размер кучи (-mh)

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

Значение по умолчанию для данной опции составляет 1024 или 65535 байт (последнее значение также является максимальным).

Размер стека (-ms)

Данный параметр имеет тот же самый смысл, что и размер стека программы-интерпретатора, и, так же как и размер кучи, используется при выполнении функции preinit. Конкретный его минимально необходимый размер определяется уровнем вложенности вызовов/обращений к другим функциям из preinit.

Значение по умолчанию для этого параметра обычно равно 50 или 512 элементов, а максимальное зависит от конкретной системы, но, как правило, стек переполняется при 8000 или более элементах.

Виртуальный кэш объектов (-m)

Эту область памяти компилятор использует для хранения откомпилированных представлений объектов и функций. Поскольку компилятор "умеет" работать с виртуальной памятью, размер кэша может быть несколько меньше, чем реальные потребности в памяти у конечной игры. Как правило, указывать размер объектного кэша не требуется, поскольку компилятор в ходе работы автоматически выделяет под кэш дополнительные объемы памяти по мере необходимости.

Однако, поскольку компилятору требуется память не только для кэша, могут возникнуть ситуации (как правило, в условиях жесткого дефицита оперативной памяти), когда кэш разрастется до такой степени, что под другие нужды памяти компилятору уже не хватит. В таких случаях компилятор аварийно завершит свою работу, выведя при этом сообщение об ошибке, в котором будет указан размер кэша на момент сбоя; после этого рекомендуется перезапустить компилятор, задав для опции -m значение, несколько меньшее указаного в сообщении об ошибке. Например, при "вылете" компилятора при размере кэша 256000 байт имеет смысл попытаться перезапустить его, указав опцию -m 200000 (чтобы ограничить объектный кэш 200000 байт).

Некоторые версии компилятора (например, для "Маков") не позволяют изменить это значение - оно всегда будет соответствовать максимально допустимому. В таких случаях следует средствами операционной системы увеличить размер доступной приложению-компилятору памяти (если ОС не делает этого самостоятельно).

Конфигурационные файлы

Для операционных систем без графического интерфейса компилятор TADS позволяет повысить удобство работы с ним, давая возможность разместить набор опций командной строки в конфигурационном файле. Этот файл будет считываться всякий раз при запуске компилятора. Зарезервированное имя конфигурационного файла - CONFIG.TC. Компилятор TADS ищет файл с таким именем сначала в текущем каталоге, а в случае неудачи - в каталоге, из которого запущен исполняемый файл компилятора. Это позволяет использовать несколько наборов опций: один - "по умолчанию" (в файле, сохраняемом в одном каталоге с компилятором); а также наборы опций для каждой игры, сохраняемые в каталогах с исходным кодом этих игр. Если файла с таким названием нет ни в текущем каталоге, ни в каталоге компилятора, то он и не используется.

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

Например, если вы хотите указать в качестве стандартных опций компиляции ограничение виртуального объектного кэша в 128000 байт, использование файла подкачки с именем SWAP.DAT на диске D:, а также поиск включаемых в текст файлов в каталоге c:\tads\include, то можно создать следующий конфигурационный файл:

  -m 128000 -tf d:\swap.dat
  -I c:\tads\include 

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

  tc -m 256000 -I c:\myinc mygame.t 

Опция -m 256000 замещает аналогичную опцию конфигурационного файла. Опции, связанные с каталогом для поиска включаемых в исходный код игры файлов, работают несколько по-иному, так как они имеют аддитивный характер: заданный в командной строке опцией -I c:\myinc каталог будет добавлен к списку путей для поиска; однако, в силу все того же приоритета, добавлен он будет перед каталогом, указанным в конфигурационном файле (иначе говоря, если имеется два файла с одинаковым именем в c:\myinc и c:\tads\include, будет использован файл именно из c:\myinc).

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

Что полезно знать про сообщения об ошибках

Когда компилятор встречает в качестве первого "значащего" символа строки файла точку с запятой или правую фигурную скобку ("}") внутри строкового значения (заключенного в одинарные или двойные кавычки), он выводит предупреждение о том, что вы, вероятно, забыли закрыть это строковое значение кавычкой справа. Это, конечно, просто "догадка" компилятора, однако если вы форматируете свой исходный код в соответствии с неписанными соглашениями, принятыми в advr.t (каждая функция заканчивается правой фигурной скобкой, которая является единственным символом в строке; каждое определение объекта завершается точкой с запятой, также являющейся единственным символом в строке), компилятор практически не будет ошибаться при обнаружении "незакрытых" строк. Обратите внимание, что конец незакрытого строкового значения необязательно будет совпадать с номером строки, указываемым компилятором в предупреждающем сообщении, однако это сообщение позволит по крайней мере локализовать объект/функцию, где это строковое значение располагается.

В настоящее время компилятор выводит сообщение об ошибке в случае, если автор игры пытается использовать self внутри функции. Это никогда не допускалось, но версии компилятора вплоть до TADS 2.1 не распознавали данную ошибку, и она обнаруживалась только при исполнении соответствующего кода.

Предупреждающие сообщения, которые компилятор выдает для опциональных объектов и функций (таких, как parseError и commandPrompt) не выдаются при уровне подробности сообщений меньшем, чем 2. Многих пользователей данные сообщения только сбивают с толку и раздражают; кроме того, эти сообщения практически никогда не указывают на реальные проблемы в исходном коде, а носят "параноидальный" характер. В связи с этим компилятор не будет выводить их, если его специально об этом не "попросить".

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

Особенности компиляции в TADS Workbench

Графическая среда разработки TADS Workbench позволяет использовать все опции компилятора командной строки, плюс предоставляет ряд дополнительных возможностей.

Все настройки, связанные с компиляцией, сосредоточены в меню Built (переводится устоявшимся исконно русским термином - "билд";). Первый пункт - Compile and Run (компилировать и запустить) осуществляет компиляцию кода с включением отладочной информации (эквивалентно опции -ds2 компилятора командной строки) с последующем запуском игры (в случае, если компиляция завершилась успешно).

Следующий пункт Compile for Debugging (компилировать для отладки) полностью аналогичен предыдущему, однако запуска игры при этом не происходит.

Команда Compile for Release (компилировать для релиза) выполняет компиляцию игры в файл формата .gam без отладочной информации, то есть файл игры будет готов к публикации.

Compile Windows .EXE (компилировать исполняемый файл (.EXE) для Windows) создает исполняемый файл Windows, также готовый к публикации. В исполняемый файл, помимо самой игры, включается и мультимедийный интерпретатор TADS для Windows, что позволяет игроку запускать его непосредственно, не скачивая и не устанавливая дополнительных программ.

Build Windows Installer (компилировать инсталлятор для Windows) создает программу-инсталлятор, устанавливающую игру на компьютер пользователя. Как и в предыдущем случае, игроку не потребуется никаких дополнительных файлов для запуска игры.

Создание инсталлятора дает ряд преимуществ по сравнению с простым исполняемым файлом или файлом формата .gam. Во-первых, так же, как и для исполняемого файла, игрокам не потребуется дополнительно скачивать интерпретатор. Во-вторых, в дистрибутив есть возможность включить дополнительные файлы (например, файл с пояснениями или с прохождением); эти дополнительные файлы будут распакованы и установлены на компьютер игрока, когда тот запустит инсталлятор. Кроме того, создание дистрибутива позволит назначить пиктограмму для вашей игры, а ссылка на игру будет размещена в меню "Пуск" Windows. Наконец, при таком варианте распространения игры на компьютер пользователя будет установлена утилита деинсталляции, которая позволит с легкостью удалить игру даже человеку, совершенно незнакомому с работой компьютера.

Обратите внимание, что скомпилировать приложение или инсталлятор можно только из TADS Workbench - компилятор командной строки такой возможности не предоставляет.

Пункт Settings... (настройки) открывает диалоговое окно, позволяющие осуществить более тонкую настройку параметров компиляции. Данное диалоговое окно разделено на две половины: слева расположена древовидная структура с "каталогами" (категориями) и "подкаталогами" настроек; справа в зависимости от выбранной категории отображаются элементы, позволяющие настраивать соответствующие параметры компиляции.

В категории Files (файлы) сосредоточены настройки, управляющие размещением файлов, связанных с созданием игры.

Подкатегория Source (исходный код) посвящена установкам исходных файлов игры. В поле Source file (файл исходника) необходимо задать главный файл с исходным кодом, который может ссылаться на все остальные файлы (фактически это аналог имени файла, задаваемого в качестве аргумента при запуске компилятора из командной строки). В список Graphics and Sound Resource files (файлы ресурсов графики и звука) можно включить любые внешние мультимедийные файлы, которые будет использовать ваша игра (в настоящее время TADS поддерживает графические форматы JPEG, PNG, MNG, а также звуковые файлы MIDI, MP3, WAV и Ogg Vorbis). Для того, чтобы добавлять такие файлы по одному, служит кнопка Add File (добавить файл); вы также можете добавлять целые каталоги, используя кнопку Add Folder (добавить каталог). Ресурсы можно также добавлять путем перетаскивания из окна Windows Explorer в поле данного списка. По умолчанию ресурсы будут включаться в скомпилированный файл игры, однако вы можете использовать и внешние ресурсные файлы, используя кнопку Add RSn. File (добавить файл RSn). Внешние ресурсные файлы имеют то же имя, что и основной файл скомпилированной игры, к которому добавляется расширение вида "RSn", где n - порядковый номер файла: .RS0, .RS1 и т. д. (нумерация осуществляется автоматически, число файлов не ограничено - 11-й файл получит расширение .RS10). После этого вы сможете группировать включаемые вами в игру мультимедийные файлы по ресурсам, просто размещая имя мультимедийного файла под именем ресурсного файла. в который его необходимо включить. Кнопка Remove (удалить) служит для удаления файлов из данного списка. Подробнее об использовании графики и звука в TADS-играх можно почитать в соответствующей главе.

Подкатегория Include (включаемые файлы) позволяет настроить параметры для дополнительных файлов, включаемых в исходный код игры при помощи директивы #include. Собственно, она содержит единственный элемент управления - список Directories to search for #include files (каталоги для поиска файлов, включаемых в код игры). Обычно в этом списке должен содержаться каталог, в котором лежит основной файл игры, а также системный каталог TADS (так как из него, как правило, берутся файлы стандартных библиотек advr.t и stdr.t). Для добавления каталогов в список служит кнопка Add (добавить). В целом данная вкладка аналогична опции -i компилятора командной строки.

В подкатегории Special (дополнительно) можно выбрать "обложку" для игры и пиктограмму для исполняемого файла игры. Для этого используются поля Cover Art Image (изображение для обложки) и EXE file icon (пиктограмма исполняемого файла) соответственно.

Подкатегория Output (выходные файлы) служит для определения имен файлов, в которые будет помещена скомпилированная игра. В первом поле - Debugging .GAM file (файл .GAM для отладки) - указывается имя файла игры, содержащего отладочную информацию. Данное поле недоступно для изменения - имя этого файла всегда идентично имени главного файла с исходным кодом (меняется только расширение). (Обратите внимание, что компилятор никогда не включает в отладочную версию игры мультимедийные ресурсы, т. е. они в этом случае должны присутствовать в виде внешних файлов). В поле Release .gam file (файл .gam для релиза) указывается имя файла, куда будет компилироваться версия игры, не содержащая отладочной информации (по команде Compile for Release). В принципе рекомендуется давать ему название, отличное от названия файла игры для отладки, чтобы при перекомпиляции одна версия игры не затирала другую, однако в конечном итоге это дело личного стиля работы автора. Наконец, последнее поле - Executable (.EXE) file (исполняемый файл .EXE) - задает имя файла, который будет формироваться по команде Compile Windows .EXE.

Категория Compiler (компилятор), как понятно из названия, служит для управления опциями компилятора, а также для работы с директивами препроцессинга.

Подкатегория Defines (определения символов) позволяет задавать и отменять определения символов препроцесинга. В списке Symbols to #define: (символы, которые следует определить) перечисляются определяемые символы препроцессинга. Их можно добавлять, либо напрямую редактируя список, либо используя кнопку Add (добавить). При нажатии этой кнопки выводится диалог Add #define Macro (добавить макрос #define), в котором можно указать имя символа (поле Macro Name) и его значение (поле Expansion). Список Symbols to #undefine: (символы, определение которых следует отменить) редактируется только напрямую и позволяет отменить определения символов, которые в противном случае компилятор определил бы автоматически. В целом же данная подкатегория соответствует опции -D компилятора.

Подкатегория Advanced (дополнительно) "отвечает" за работу с большинством остальных опций компилятора. При выборе флажка Ignore case (in object names, functions, etc.) (игнорировать регистр (в именах объектов, функций и т. д.)) компилятор перестает быть чувствительным к регистру символов (см. опцию -case). Флажок C-style Operators ("=" for assignments, "==" for comparison) (Операторы в стиле языка Си: "=" - присваивание, "==" - сравнение) аналогичен опции -C. Флажок Character Mapping File: (файл с таблицей символов) позволяет указать (в расположеном рядом с ним поле ввода, с использованием кнопки Browse... (пролистать)) имя файла, который будет определять, как должны интерпретироваться символы расширенного набора ASCII; подробнее см. опцию -ctab. В поле Additional command-line options: (дополнительные опции командной строки) можно указать любые другие доступные опции компилятора.

И, наконец, последняя категория - Packaging (создание дистрибутива) с единственной подкатегорией Windows SETUP (инсталлятор для Windows) позволяет задать параметры дистрибутива игры, который создается при выборе соответствующей команды. В поле Setup Program File: (имя файла программы-инсталлятора) указывается имя исполняемого файла результирующего дистрибутива. Это имя можно набрать руками или выбрать среди уже имеющихся на диске файлов, используя расположенную слева от данного поля кнопку Browse (пролистать). В поле Installer Options: (опции инсталлятора) задаются параметры дистрибутива. Их также можно набирать непосредственно с клавиатуры или использовать для их указания кнопку Edit (редактировать). При нажатии последней появится диалоговое окно со следующими полями:
Display name: (отображаемое имя) - имя игры в том виде, как его увидит пользователь в ходе инсталляции;
Saved Game Extension: (расширение файлов сохранений) - расширения имен файлов для пользовательских сохранений в ходе игры. По умолчанию для сохраненных (R)TADS-игр принято расширение .SAV. Задав в этом пункте другое расширение, можно добиться того, чтобы при двойном щелчке мышью на этом файле открывалась именно ваша игра. Это расширение необходимо выбрать уникальным для данной игры, чтобы не происходило "конфликта интересов" разных программ при открытии такого файла;
Default Program Directory: (каталог установки по умолчанию) - каталог, в который будет предложено установить игру при инсталляции. Локальный префикс каталога для установки программ (обычно C:\Program Files\) будет подставляться инсталлятором автоматически, поэтому указывать его здесь не нужно;
Default Start Menu Folder: (папка меню "Пуск" по умолчанию) - название папки в меню "Пуск", которое будет предложено для данной игры при инсталляции;
License file: (файл с лицензией) - текстовый файл, содержащий информацию по авторскому праву/лицензии для данной игры. Пользователю будет предложено прочесть данный текст в ходе инсталляции. Название файла можно ввести вручную, а можно выбрать его, используя кнопку Browse (пролистать);
Read-me file: (файл с дополнительной информацией, файл "прочти меня") - текстовый или HTML-файл, который будет представлен пользователю сразу после завершения инсталляции игры. Обычно в таком файле размещают важную дополнительную информацию по игре. Название файла можно ввести вручную, а можно выбрать его, используя кнопку Browse (пролистать);
Read-me Title: (ссылка на файл с дополнительной информацией) - этот текст будет использован в качестве имени ярлыка, ссылающегося на файл с дополнительной информацией в меню "Пуск".

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

FILE=имя_включаемого_файла

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

Рекомендуемая структура каталогов

Примечание переводчика: Эта тема не относится напрямую к компилятору, однако тесно связана с его работой. Поэтому она освещена здесь.

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

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

Файлы медийных ресурсов рекомендуется располагать в том же каталоге, что и файл с игрой, откомпилированной для отладки, либо в подкаталоге соответствующего каталога. Отладчик TADS Workbench никогда не включает ресурсы в файл игры, компилируемой для отладки; вместо этого он подключает их по мере надобности "на лету", в ходе исполнения игры. В то же время при компиляции для релиза TADS включает все ресурсы в файл конечной игры (таким образом, автору не потребуется включать в дистрибутив игры еще и файлы ресурсов). Таким образом, готовая к релизу игра будет подгружать ресурсы непосредственно из файла .GAM. Располагая мультимедийные ресурсы в каталоге с отладочным файлом игры либо его подкаталогах, вы обеспечиваете полностью одинаковое поведение в отношении ресурсов отладочной версии игры и ее релиза.

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

Программный каталог TADS:
C:\Program Files\TADS Toolkit

Основной каталог игры:
C:\Games\MyGame

Каталог для исходников игры:
C:\Games\MyGame\source

Каталог для скомпилированной игры:
C:\Games\MyGame\GAM

Каталог графических ресурсов (файлы JPEG, PNG и MNG):
C:\Games\MyGame\GAM\images

Каталог аудиоресурсов (MIDI, WAV, MP3, Ogg Vorbis):
C:\Games\MyGame\GAM\sounds