Индивидуальные исходные комплекты

Традиционным форматом исходных комплектов в Eclipse была папка, содержащая в себе файлы src.zip для всех модулей,включенных в определенный компонент. Начиная с версии 3.4, Eclipse поставляется с индивидуальными исходными комплектами. Для каждого комплекта имеется соответствующий исходный комплект, который представляет собой jar-файл, содержащий исходный код для этого комплекта. Тем самым увеличивается гибкость доставки исходного кода и смягчается влияние некоторых ошибок, которые связаны с длиной пути и могут возникать на некоторых платформах.

Eclipse-SourceBundle

Исходный комплект идентифицирован наличием заголовка Eclipse-SourceBundle в манифесте. Формат этого заголовка следующий:

Eclipse-SourceBundle: <bundle-id>;version=<version>;roots:="root1, root2"

Идентификатор комплекта и версия указывают на комплект, которому соответствует включенный исходный код. Директива roots указывает на папки внутри исходного комплекта, фактически содержащего в себе исходный код. Если директива roots не указана, предполагается значение ".".

Библиотеки файлов классов сопоставлены с исходными расположениями предсказуемым образом. Корень модуля сопоставляется с корнем исходного комплекта. Это обычно принято для большинства модулей, заархивированных в файлы jar. Если модуль содержит дополнительные библиотеки "foo/lib.jar", предполагается, что исходный код расположен в соответствующих папках "foo/libsrc/" в исходных комплектах.

Генерирование индивидуальных исходных комплектов

PDE/Build может автоматически генерировать индивидуальные исходные комплекты, но только при консольной компоновке. Генерирование индивидуальных исходных комплектов можно включить, указав:

individualSourceBundles=true

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

generate.feature

В файле компонента build.properties свойство generate.feature заставляет pde.build генерировать исходный компонент.
generate.feature@<ид исходного компонента> = <feature id> [, feature@<feature id>]* [, plugin@<plugin id>]* [, exclude@<plugin id>]*

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

Модули, которые были включены в исходный компонент посредством синтаксиса plugin@, не получат соответствующих исходных комплектов. Это удобно при добавлении модулей документов к исходному компоненту.

Запись exclude@ является новой для генерирования индивидуального исходного кода. Некоторые модули, которые были включены в компонент запуска (т.е. модули документов или фрагменты, содержащие только стандартный код), могут не иметь исходного кода и должны быть исключены из сгенерированного исходного компонента. Запись exclude@ поддерживает атрибут version (версия).

Пример:
generate.feature@org.eclipse.jdt.source=org.eclipse.jdt, plugin@org.eclipse.jdt.doc.isv;unpack="false",exclude@org.eclipse.jdt.doc.user

generate.plugin

В прежнем формате свойство generate.plugin генерировало исходный модуль, основанный на содержимом определенного компонента. При генерировании индивидуальных исходных комплектов, это свойство изменилось и основывается теперь на определенном модуле:

generate.plugin@<исходный модуль>=<ид модуля>

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

Пример: Компонент sdk.examples раньше выглядел так:

   	<feature id="org.eclipse.sdk.examples"  ... > 
		....
		<plugin id="org.eclipse.sdk.examples.source"  version="0.0.0"/>
		<plugin id="org.eclipse.sdk.examples.source.win32.win32.x86" version="0.0.0"/>
	</feature>

generate.plugin@org.eclipse.sdk.examples.source=org.eclipse.sdk.examples

и изменился на:

	<feature id="org.eclipse.sdk.examples" ...>
		...
		<plugin id="org.eclipse.compare.examples.source"  version="0.0.0"/>
		<plugin id="org.eclipse.debug.examples.core.source" version="0.0.0"/>
		<plugin id="org.eclipse.swt.examples.source" version="0.0.0"/>
	</feature>

generate.plugin@org.eclipse.compare.examples.source=org.eclipse.compare.examples generate.plugin@org.eclipse.debug.examples.core.source=org.eclipse.debug.examples.core generate.plugin@org.eclipse.swt.examples.source=org.eclipse.swt.examples

generateSourceBundle

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

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

generateSourceBundle=false

Нестандартное содержимое

Нестандартное содержимое всегда можно добавлять к сгенерированным исходным комплектам с помощью пользовательского обратного вызова post.gather.source в комплекте запуска. (См. раздел Этапы пользовательской компоновки компонентов и модулей).

При этом следует задать свойство "src.additionalRoots" в файле build.properties модуля так, чтобы при генерировании исходного комплекта была верно указана директива roots в заголовке Eclipse-SourceBundle.

Пример:

org.junit4 :
   build.properties
      src.includes = about.html,junitsrc.zip
      src.additionalRoots=junitsrc
      customBuildCallbacks=customBuildCallbacks.xml

   customBuildCallbacks.xml
    	<target name="post.gather.sources" >
		<mkdir dir="${target.folder}/junitsrc"/>
		<unzip src="${target.folder}/junitsrc.zip" dest="${target.folder}/junitsrc" overwrite="false"/>
		<delete file="${destination.temp.folder}/junitsrc.zip" />		
	</target>

Исходный модуль торговых знаков

Ранее сгенерированный исходный модуль служил модулем торговых знаков для сгенерированного исходного компонента. Файлы торговых знаков (about.properties, eclipse32.gif и др.) предоставлялись посредством каталога sourceTemplatePlugin в первоначальном компоненте.

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

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

sourceTemplatePlugin vs sourceTemplateBundle

Раньше содержимое каталога sourceTemplatePlugin первоначального компонента копировалось в исходный модуль. При генерировании индивидуальных исходных комплектов эта особенность сохраняется только для исходного модуля торговых знаков (см.выше).

Для всех остальных исходных комплектов, содержимое каталога sourceTemplateBundle будет скопировано поверх.