В этом разделе рассказывается о том, как увеличить объем. Постройте, чтобы удовлетворить ваши местные требования и #8212; прежде всего, чтобы добавить поддержку нестандартных инструментов. Прежде чем мы начнем, убедитесь, что вы прочитали и подтолкнули концепцию метацели,раздел под названием “ Концепции ”, который имеет решающее значение для понимания оставшегося материала.

Текущая версия Boost. Строительство имеет три уровня целей, перечисленных ниже.

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

	Warning
	Весь рост. Встроенные функции, связанные с джемом, такие как<DEPENDS>или<ALWAYS>, работают на джем-мишенях. Применение их к метацелям или конкретным целям не имеет никакого эффекта.

local a = [ new action $(source) : common.copy : $(property-set) ] ;
local t = [ new file-target $(name) : CPP : $(project) : $(a) ] ;

return [ virtual-target.register $(t) ] ;
return [ sequence.transform virtual-target.register : $(targets) ] ;

Скажем, вы пишете приложение, которое генерирует код C++. Если вы когда-нибудь делали это, вы знаете, что это нехорошо. Встраивать большие части кода C++ в строковые буквы очень неудобно. Гораздо лучшим решением является:

Это довольно легко достичь. Вы пишете специальные дословные файлы, которые являются только C++, за исключением того, что первая строка файла содержит имя переменной, которая должна быть сгенерирована. Создается простой инструмент, который берет дословный файл и создает cpp-файл с одной<char*>переменной, имя которой взято из первой строки дословного файла и значение которой является правильно цитируемым содержимым файла.

Посмотрим, что поднимется. Строить можно.

Во-первых, Буст. Build не имеет понятия о «дословных файлах». Вы должны зарегистрировать новый тип цели. Это делает следующий код:

import type ;
type.register VERBATIM : verbatim ;

Первый параметрtype.registerдает название заявленного типа. По соглашению, это верхний регистр. Второй параметр — суффикс для файлов этого типа. Так что, если увеличить.<code.verbatim>в списке источников, он знает, что это тип<VERBATIM>.

Далее, скажите Буту. Постройте, что дословные файлы могут быть преобразованы в файлы C++ за один шаг сборки. Генераторявляется шаблоном для этапа сборки, который преобразует цели одного типа (или набора типов) в другой. Наш генератор будет называться<verbatim.inline-file>; он преобразует<VERBATIM>файлов в<CPP>файлы:

import generators ;
generators.register-standard verbatim.inline-file : VERBATIM : CPP ;

Наконец, вы должны проинформировать Бута. Создайте команды оболочки, используемые для этой трансформации. Об этом говорится в декларации<actions>.

actions inline-file
{
    "./inline-file.py" $(<) $(>)
}

Теперь мы готовы связать все это вместе. Поместите весь код выше в файл<verbatim.jam>, добавьте<import verbatim ;>к<Jamroot.jam>, и вы можете написать следующее в своем Jamfile:

exe codegen : codegen.cpp class_template.verbatim usage.verbatim ;

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

В последующих разделах мы рассмотрим этот пример и подробно рассмотрим все механизмы. Полный код доступен в каталоге<example/customization>.

Первое, что мы сделали во введении, это объявили новый тип цели:

import type ;
type.register VERBATIM : verbatim ;

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

Первые два параметра правила<type.register>— название нового типа и список связанных с ним расширений. Файл с расширением из списка будет иметь заданный целевой тип. В случае, когда цель заявленного типа генерируется из других источников, будет использоваться первое указанное расширение.

Иногда вы хотите изменить суффикс, используемый для генерируемых целей, в зависимости от свойств сборки, таких как набор инструментов. Например, некоторые компиляторы используют расширение<elf>для исполняемых файлов. Вы можете использовать правило 113:

type.set-generated-target-suffix EXE : <toolset>elf : elf ;

Новый тип цели может быть унаследован от существующего.

type.register PLUGIN : : SHARED_LIB ;

Приведенный выше код определяет новый тип, полученный из<SHARED_LIB>. Первоначально новый тип наследует все свойства базового типа — в частности генераторы и суффикс. Как правило, вы каким-то образом измените новый тип. Например, с помощью<type.set-generated-target-suffix>можно установить суффикс для нового типа. Или можно написать специальный генератор для нового типа. Например, он может генерировать дополнительную метаинформацию для плагина. В любом случае, тип<PLUGIN>может использоваться всякий раз, когда<SHARED_LIB>может. Например, вы можете напрямую связать плагины с приложением.

Тип может быть определен как «основной», и в этом случае увеличивается. Build автоматически объявит основное целевое правило для построения целей такого типа. Более подробную информацию можно найтипозже.

class verbatim-scanner : common-scanner
{
    rule pattern ( )
    {
        return "//###include[ ]*\"([^\"]*)\"" ;
    }
}

scanner.register verbatim-scanner : include ;

type.set-scanner VERBATIM : verbatim-scanner ;

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

Для каждого дополнительного инструмента – буст. Необходимо создать объект, называемый генератором. Этот объект имеет определенные типы целей, которые он принимает и производит. Используя эту информацию, Boost. Build может автоматически вызывать генератор. Например, если вы объявите генератор, который принимает цель типа<D>и производит цель типа<OBJ>, при размещении файла с протяженностью<.d>в списке источников вызовет Boost. Создайте, чтобы вызвать генератор, а затем связать полученный объектный файл с приложением. (Конечно, это требует, чтобы вы указали, что расширение<.d>соответствует типу<D>.)

Каждый генератор должен быть экземпляром класса, полученного из класса<generator>. В простейшем случае вам не нужно создавать производный класс, а просто создать экземпляр класса<generator>. Давайте рассмотрим пример, который мы видели во введении.

import generators ;
generators.register-standard verbatim.inline-file : VERBATIM : CPP ;
actions inline-file
{
    "./inline-file.py" $(<) $(>)
}

Объявляем стандартный генератор, указывая его идентификатор, тип источника и тип цели. При вызове генератор создаст цель типа<CPP>с целью источника типа<VERBATIM>в качестве единственного источника. Но какая команда будет использоваться для создания файла? В Boost.Build действия уточняются с помощью названных блоков «действий», а при создании целей следует указывать название блока действий. По соглашению, генераторы используют то же название блока действия, что и их собственный идентификатор. Так, в приведенном выше примере блок действий «встроенного файла» будет использоваться для преобразования источника в цель.

Существует два основных типа генераторов: стандартные и составные, которые зарегистрированы по<generators.register-standard>и<generators.register-composing>правилам соответственно. Например:

generators.register-standard verbatim.inline-file : VERBATIM : CPP ;
generators.register-composing mex.mex : CPP LIB : MEX ;

Первый (стандартный) генератор беретодиночныйисточник типа<VERBATIM>и производит результат. Второй (составляющий) генератор принимает любое количество источников, которые могут иметь тип<CPP>или<LIB>. Составные генераторы обычно используются для генерации целевого типа верхнего уровня. Например, первый генератор, используемый при создании<exe>цели, представляет собой составной генератор, соответствующий соответствующему линкеру.

Вы также должны знать о двух конкретных функциях регистрации генераторов:<generators.register-c-compiler>и<generators.register-linker>. Первый настраивает сканирование зависимостей заголовка для файлов C, а секунды обрабатывают различные сложности, такие как библиотеки поиска. По этой причине вы всегда должны использовать эти функции при добавлении поддержки компиляторов и линкеров.

(Нужна записка о UNIX)

Custom generator classes

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

class custom-generator : generator
{
    rule __init__ ( * : * )
    {
        generator.__init__ $(1) : $(2) : $(3) : $(4) : $(5) : $(6) : $(7) : $(8) : $(9) ;
    }
}
generators.register
  [ new custom-generator verbatim.inline-file : VERBATIM : CPP ] ;

Этот генератор будет работать точно так же, как генератор<verbatim.inline-file>, который мы определили выше, но можно настроить поведение с помощью основных методов класса<generator>.

Есть два способа заинтересовать. Метод<run>отвечает за общий процесс — он принимает ряд исходных целей, преобразует их в правильные типы и создает результат. Метод<generated-targets>называется, когда все источники преобразуются в правильные типы для фактического создания результата.

Метод<generated-targets>может быть переопределен, если вы хотите добавить дополнительные свойства к генерируемым целям или использовать дополнительные источники. Например, предположим, что у вас есть инструмент анализа программы, который должен иметь имя исполняемого файла и список всех источников. Естественно, вы не хотите перечислять все исходные файлы вручную. Вот как метод 150 может автоматически найти список источников:

class itrace-generator : generator {
....
    rule generated-targets ( sources + : property-set : project name ? )
    {
        local leaves ;
        local temp = [ virtual-target.traverse $(sources[1]) : : include-sources ] ;
        for local t in $(temp)
        {
            if ! [ $(t).action ]
            {
                leaves += $(t) ;
            }
        }
        return [ generator.generated-targets $(sources) $(leafs)
          : $(property-set) : $(project) $(name) ] ;
    }
}
generators.register [ new itrace-generator nm.itrace : EXE : ITRACE ] ;

Метод<generated-targets>будет называться с одной исходной мишенью типа<EXE>. Призыв к<virtual-target.traverse>возвращает все цели, от которых зависит исполняемый файл, и мы также находим файлы, которые не производятся из чего-либо. Найденные цели добавляются к источникам.

Метод<run>может быть перегружен, чтобы полностью настроить работу генератора. В частности, преобразование источников в желаемые типы может быть полностью настроено. Вот еще один реальный пример. Тесты для библиотеки Boost Python обычно состоят из двух частей: программы Python и файла C++. Файл C++ компилируется с расширением Python, которое загружается программой Python. Но в вероятном случае, если оба файла имеют одинаковое имя, созданное расширение Python должно быть переименовано. В противном случае программа Python будет импортировать себя, а не расширение. Вот как это можно сделать:

rule run ( project name ? : property-set : sources * )
{
    local python ;
    for local s in $(sources)
    {
        if [ $(s).type ] = PY
        {
            python = $(s) ;
        }
    }
    
    local libs ;
    for local s in $(sources)
    {
        if [ type.is-derived [ $(s).type ] LIB ]
        {
            libs += $(s) ;
        }
    }
    local new-sources ;
    for local s in $(sources)
    {
        if [ type.is-derived [ $(s).type ] CPP ]
        {
            local name = [ $(s).name ] ;    # get the target's basename
            if $(name) = [ $(python).name ]
            {
                name = $(name)_ext ;        # rename the target
            }
            new-sources += [ generators.construct $(project) $(name) :
              PYTHON_EXTENSION : $(property-set) : $(s) $(libs) ] ;
        }
    }
    result = [ construct-result $(python) $(new-sources) : $(project) $(name)
                 : $(property-set) ] ;
}

Во-первых, мы разделяем все исходные тексты на файлы Python, библиотеки и C++. Для каждого источника C++ мы создаем отдельное расширение Python, вызывая<generators.construct>и передавая источник C++ и библиотеки. При необходимости мы также меняем название расширения.

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

# Declare a new free feature
import feature : feature ;
feature verbatim-options : : free ;
# Cause the value of the 'verbatim-options' feature to be
# available as 'OPTIONS' variable inside verbatim.inline-file
import toolset : flags ;
flags verbatim.inline-file OPTIONS <verbatim-options> ;
# Use the "OPTIONS" variable
actions inline-file
{
    "./inline-file.py" $(OPTIONS) $(<) $(>)
}

Сначала определим новую особенность. В 157-м стихе говорится, что всякий раз, когда Действия inline-file выполняются, значение функции<verbatim-options>добавляется к переменной<OPTIONS>и может использоваться внутри тела действия. Вам нужно будет обратиться за онлайн-помощью (--помощью), чтобы найти все особенности правила<toolset.flags>.

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

Большинство функций должны иметь фиксированный набор значений, который является портативным (инструментно-нейтральным) по всему классу инструментов, с которыми они предназначены для работы. Пользователь не должен корректировать значения для точного инструмента. Например,<<optimization>speed>имеет одинаковое значение для всех компиляторов C++, и пользователю не нужно беспокоиться о точных опциях, переданных командной строке компилятора.

Помимо таких переносных функций, существуют специальные «сырые» функции, которые позволяют пользователю передавать любое значение параметрам командной строки для конкретного инструмента, если это необходимо. Например, функция<<cxxflags>>позволяет передавать любые параметры командной строки компилятору C++. Функция<<include>>позволяет пропускать любую строку, предшествующую<-I>, и интерпретация зависит от инструмента. (См.раздел под названием “ Могу ли я получить вывод внешней программы с помощью Boost). Переменная джема? & #8221;для примера очень умного использования этой функции. Конечно, всегда следует стремиться использовать портативные функции, но они по-прежнему предоставляются в качестве бэкдора, чтобы убедиться, что они улучшаются. Построение не отнимает у пользователя никакого контроля.

Использование портативных функций является хорошей идеей, потому что:

Steps for adding a feauture

Добавление функции требует трех шагов:

Another example

Вот еще один пример. Давайте посмотрим, как мы можем создать функцию, которая относится к цели. Например, при связывании динамических библиотек в Windows иногда требуется указать «файл DEF», сообщив, какие функции следует экспортировать. Было бы неплохо использовать этот файл так:

        lib a : a.cpp : <def-file>a.def ;

Собственно, эта функция уже поддерживается, но в любом случае...

Variants and composite features.

Иногда вы хотите создать ярлык для некоторых функций. Например,<release>является значением<<variant>>и является ярлыком для набора признаков.

Можно определить собственные варианты сборки. Например:

variant crazy : <optimization>speed <inlining>off
                <debug-symbols>on <profiling>on ;

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

variant super_release : release : <define>USE_ASM ;

В этом случае<super_release>будет расширяться на все свойства, указанные<release>, и дополнительные, которые вы указали.

Вы не можете использовать только функцию<variant>. Вот пример, который определяет совершенно новую функцию:

feature parallelism : mpi fake none : composite link-incompatible ;
feature.compose <parallelism>mpi : <library>/mpi//mpi/<parallelism>none ;
feature.compose <parallelism>fake : <library>/mpi//fake/<parallelism>none ;

Это позволит указать значение функции<parallelism>, которая расширится до ссылки на необходимую библиотеку.

Основное правило цели (например, & #8220;exe& #8221; или & #8220;lib& #8221;) создает цель верхнего уровня. Вполне вероятно, что вы захотите заявить о себе, и есть два способа сделать это.

Первый способ применяется, когда ваше целевое правило должно просто создавать цель определенного типа. В этом случае для вас уже определено правило! Когда вы определяете новый тип, увеличивайте. Построение автоматически определяет соответствующее правило. Название правила получено из названия типа, путем сокращения всех букв и замены подчеркиваний тире. Например, если вы создаете модуль<obfuscate.jam>, содержащий:

import type ;
type.register OBFUSCATED_CPP  : ocpp ;
import generators ;
generators.register-standard obfuscate.file : CPP : OBFUSCATED_CPP ;

и импортировать этот модуль, вы сможете использовать правило «запутанный-cpp» в Jamfiles, который преобразует источник в тип OBFUSCATED_CPP.

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

lib codegen : [ glob *.cpp ] ;

Если вы хотите сделать его еще проще, вы можете добавить следующее определение в файл<Jamroot.jam>:

rule glib ( name : extra-sources * : requirements * )
{
    lib $(name) : [ glob *.cpp ] $(extra-sources) : $(requirements) ;
}

Позволяет уменьшить Jamfile, чтобы просто

glib codegen ;

Обратите внимание, что поскольку вы можете связать пользовательский генератор с целевым типом, логика построения может быть довольно сложной. Например, модуль<boostbook>объявляет целевой тип<BOOSTBOOK_MAIN>и пользовательский генератор для этого типа. Вы можете использовать это в качестве примера, если ваше основное правило цели нетривиально.

Если ваши расширения будут использоваться только в одном проекте, они могут быть помещены в отдельный файл<.jam>и импортированы вашим<Jamroot.jam>. Если расширения будут использоваться во многих проектах, пользователи будут благодарны вам за завершающий штрих.

Правило<using>обеспечивает стандартный механизм загрузки и настройки расширений. Чтобы это работало, ваш модуль должен обеспечить правило<init>. Правило будет называться с теми же параметрами, которые были переданы правилу<using>. Набор допустимых параметров определяется вами. Например, вы можете позволить пользователю указать пути, версии инструментов и другие параметры.

Вот некоторые рекомендации, которые помогают повысить. Построить более последовательно: