Интерфейс загруженного объекта

Для полезного использования загруженные объекты должны иметь возможность взаимодействовать с GNU make. Это взаимодействие включает как интерфейсы, предоставляемые загруженным объектом для файлов make, так и интерфейсы, которые make предоставляет загруженному объекту для управления работой make.

Интерфейс между загруженными объектами и make определяется C-заголовочным файлом gnumake.h. Все загруженные объекты, написанные на C, должны включать этот заголовочный файл. Любой загруженный объект, написанный не на C, должен реализовать интерфейс, определенный в этом заголовочном файле.

Как правило, загруженный объект регистрирует одну или несколько новых функций GNU make с помощью функции gmk_add_function внутри своей функции настройки. Реализации этих функций make могут использовать функции gmk_expand и gmk_eval для выполнения своих задач, а затем необязательно возвращать строку в качестве результата расширения функции.

Лицензирование загруженных объектов

Каждое динамическое расширение должно определять глобальную переменную plugin_is_GPL_compatible для подтверждения, что оно лицензировано по совместимой с GPL лицензии. Если эта переменная не существует, make выводит критическую ошибку и завершается при попытке загрузить ваше расширение.

Объявленный тип переменной должен быть int. Однако ей не нужно быть в какой-либо выделенной секции. Код просто проверяет, что переменная существует в глобальном пространстве имен. Достаточно чего-то вроде этого:

int plugin_is_GPL_compatible;

Структуры данных

gmk_floc

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

Регистрация функций

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

Используйте gmk_add_function для создания новой функции make. Ее аргументы следующие:

name

Имя функции. Именно это имя должен использовать файл make для вызова функции. Имя должно быть от 1 до 255 символов длиной и может содержать только буквенно-цифровые символы, точку («.»), дефис («-») и знак подчеркивания («_»). Оно не может начинаться с точки.

func_ptr

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

min_args

Минимальное количество аргументов, которые функция будет принимать. Должно быть между 0 и 255. GNU make проверит это и завершится с ошибкой до вызова func_ptr, если функция была вызвана с недостаточным количеством аргументов.

max_args

Максимальное количество аргументов, которые функция будет принимать. Должно быть между 0 и 255. GNU make проверит это и завершится с ошибкой до вызова func_ptr, если функция была вызвана с избыточным количеством аргументов. Если значение равно 0, то принимается любое количество аргументов. Если значение больше 0, то оно должно быть больше или равно min_args.

flags

Флаги, определяющие, как будет работать эта функция; желаемые флаги должны быть объединены побитовым ИЛИ. Если задан флаг GMK_FUNC_NOEXPAND, то аргументы функции не будут расширены перед вызовом функции; в противном случае они будут расширены предварительно.

Интерфейс зарегистрированной функции

Функция, зарегистрированная с помощью make, должна соответствовать типу gmk_func_ptr. Она будет вызвана с тремя параметрами: name (имя функции), argc (количество аргументов функции) и argv (массив указателей на аргументы функции). Последний указатель (то есть argv[argc]) будет равен null (0).

Значение возвращаемой функцией является результатом расширения функции. Если функция расширяется до пустой строки, значение возврата может быть null. В противном случае, это должен быть указатель на строку, созданную с помощью gmk_alloc. После возврата функции make владеет этой строкой и освободит её при необходимости; она не может быть доступна загруженному объекту.

Средства GNU make

GNU make предоставляет некоторые средства для использования загруженными объектами. Обычно они выполняются внутри функции настройки и/или функций, зарегистрированных через gmk_add_function, для получения или изменения данных, с которыми работает make.

gmk_expand

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

gmk_eval

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

Обратите внимание, что существует различие между gmk_eval и вызовом gmk_expand со строкой с помощью функции eval: в последнем случае строка будет расширена дважды; один раз gmk_expand, а затем снова функцией eval. Использование gmk_eval расширяет буфер только один раз, в крайнем случае (так как он считывается парсером make).

Управление памятью

Некоторые системы позволяют использовать различные схемы управления памятью. Поэтому вы никогда не должны передавать память, выделенную вами непосредственно, ни одной функции make, и не должны пытаться напрямую освободить любую память, возвращённую вам функцией make. Вместо этого используйте функции gmk_alloc и gmk_free.

В частности, строка, возвращаемая функции make функцией, зарегистрированной с помощью gmk_add_function, должна быть выделена с помощью gmk_alloc, а строка, возвращаемая функцией make gmk_expand, должна быть освобождена (когда больше не нужна) с помощью функции gmk_free.

gmk_alloc

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

gmk_free

Освобождает буфер, возвращённый вами функцией make. После того, как функция gmk_free вернёт строку, она больше не будет действительной. Если в gmk_free передаётся NULL, то никакой операции не выполняется.