Pojedyncze pakunki źródłowe

Tradycyjnym formatem pakunków źródłowych w środowisku Eclipse był folder zawierający pliki src.zip dla wszystkich wtyczek danego składnika. Począwszy od wersji 3.4 środowisko Eclipse jest dostarczane z pojedynczymi pakunkami źródłowymi. Dla każdego pakunku istnieje odpowiedni pakunek źródłowy, który jest plikiem JAR zawierającym źródło tego pakunku. Takie rozwiązanie pozwala na bardziej elastyczne dostarczanie źródła, a także eliminuje pewne problemy z długością ścieżki, które mogą występować na niektórych platformach.

Nagłówek Eclipse-SourceBundle

Pakunek źródłowy jest identyfikowany przez obecność nagłówka Eclipse-SourceBundle w jego manifeście. Format nagłówka jest następujący:

Eclipse-SourceBundle:
<identyfikator_pakunku>;version=<wersja>;roots:="katalog_główny1, katalog_główny2"

Identyfikator pakunku i wersja wskazują pakunek odpowiadający dołączonemu kodowi źródłowemu. Dyrektywa roots wskazuje foldery w pakunku źródłowym, które w rzeczywistości zawierają kod źródłowy. Jeśli dyrektywa roots nie jest określona, przyjmowana jest wartość ".".

Biblioteki plików klas są odwzorowywane na położenia źródłowe w przewidywalny sposób. Katalog główny wtyczki jest odwzorowywany na katalog główny pakunku źródłowego. Dzieje się tak w przypadku większości wtyczek spakowanych do plików JAR. Jeśli wtyczka zawiera dodatkowe biblioteki foo/lib.jar, źródło powinno znajdować się w analogicznych folderach foo/libsrc/ pakunków źródłowych.

Generowanie pojedynczych pakunków źródłowych

Komponent PDE/Build może automatycznie generować pojedyncze pakunki źródłowe, jednak tylko w procesie budowania nienadzorowanego. Generowanie pojedynczych pakunków źródłowych można włączyć, określając właściwość:

individualSourceBundles=true

Tę właściwość należy określić w pliku najwyższego poziomu konfiguracji budowania build.properties, przy czym steruje ona generowaniem całego kodu źródłowego dla tego procesu budowania. Szczegółowe informacje na temat generowania tradycyjnych wtyczek i składników źródłowych zawiera sekcja Generowanie źródłowych składników i wtyczek. Pozostałe zagadnienia na tej stronie wymagają znajomości generowania tradycyjnego kodu źródłowego.

generate.feature

Właściwość generate.feature w pliku build.properties składnika informuje komponent pde.build, że ma zostać wygenerowany składnik źródłowy.
generate.feature@<identyfikator_składnika_źródłowego>
= <identyfikator_składnika> [, feature@<identyfikator_składnika>]* [,
plugin@<identyfikator_wtyczki>]* [, exclude@<identyfikator_wtyczki>]*

Podczas generowania pojedynczych pakunków źródłowych ta właściwość jest taka jak wcześniej i obsługuje te same atrybuty (np. version, unpack, optional itp.). Różnica występuje w wynikowym składniku źródłowym. We wcześniejszej wersji składnik źródłowy zawierałby 1 wtyczkę źródłową i fragment kodu źródłowego dla każdej budowanej platformy. W nowym formacie składnik źródłowy będzie zawierał pakunek źródłowy dla każdej wtyczki/fragmentu, które są wymienione w pierwotnym składniku.

Wtyczki, które zostały włączone do składnika źródłowego za pośrednictwem składni plugin@, nie będą miały odpowiadających pakunków źródłowych. Takie rozwiązanie jest użyteczne, gdy do składnika źródłowego dodawane są wtyczki dokumentów.

Pozycja exclude@ jest nowością w przypadku generowania pojedynczego kodu źródłowego. Niektóre wtyczki zawarte w pierwotnym składniku (np. wtyczki dokumentów lub fragmenty zawierające tylko kod rodzimy) mogą nie mieć źródła i powinny zostać wykluczone z generowanego składnika źródłowego. Pozycja exclude@ obsługuje atrybut version.

Przykład:
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

W starym formacie właściwość generate.plugin generuje wtyczkę źródłową w oparciu o treść danego składnika. Gdy generowane są pojedyncze pakunki źródłowe, wtyczka źródłowa jest generowana w oparciu o daną wtyczkę:

generate.plugin@<identyfikator_wtyczki_źródłowej>=<identyfikator_wtyczki>

Właściwość generate.plugin była używana przez składniki do włączania źródła bez składnika źródłowego (choć w tle generowany był cały składnik źródłowy). W przypadku generowania pojedynczego pakunku źródłowego, składniki muszą zawierać pakunek *.source dla każdej wtyczki wraz z odpowiednią właściwością generate.plugin dla każdej z nich.

Przykład: Składnik sdk.examples wcześniej wyglądał następująco:

   	<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

Po zmianie składnik ma następującą postać:

	<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

Konkretne wtyczki mogą nie wymagać pakunków źródłowych, ponieważ w rzeczywistości nie zawierają one kodu źródłowego. Taka sytuacja może dotyczyć fragmentów specyficznych dla platformy, które zawierają tylko bibliotekę rodzimą. W takim przypadku pakunki mogą zostać wykluczone przez składnik, tak jak to przedstawiono w opisie właściwości generate.feature.

Pakunki mogą również jawnie określić we własnym pliku build.properties, że nie ma być dla nich generowany żaden pakunek źródłowy:

generateSourceBundle=false

Treść niestandardowa

Treść niestandardową można zawsze dodać do generowanych pakunków źródłowych, używając niestandardowego wywołania zwrotnego post.gather.source w pierwotnym pakunku. Więcej informacji na ten temat zawiera sekcja Etapy niestandardowego budowania składników i wtyczek.

W takim przypadku należy ustawić właściwość src.additionalRoots w pliku build.properties wtyczki tak, aby generowany pakunek źródłowy miał w nagłówku Eclipse-SourceBundle poprawną dyrektywę roots.

Przykład:

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>

Oznakowanie składnika źródłowego marką

Wcześniej wygenerowana wtyczka źródłowa pełniła dla generowanego składnika źródłowego rolę wtyczki oznakowania marką. Pliki oznakowania marką (about.properties, eclipse32.gif itp.) były udostępniane przy użyciu katalogu sourceTemplatePlugin w pierwotnym składniku.

W przypadku generowania pojedynczych pakunków źródłowych wtyczką oznakowania marką dla składnika źródłowego jest pakunek źródłowy odpowiadający pierwotnej wtyczce oznakowania marką. Oznacza to, że pliki oznakowania marką dla wtyczki oznakowania marką składnika źródłowego mogą być wnoszone przy użyciu właściwości src.includes w pierwotnej wtyczce oznakowania marką.

Folder sourceTemplatePlugin składnika, dla którego generowany jest kod źródłowy, również wnosi pliki do wtyczki oznakowania marką.

Katalog sourceTemplatePlugin a katalog sourceTemplateBundle

Wcześniej zawartość katalogu sourceTemplatePlugin pierwotnego składnika była kopiowana do wtyczki źródłowej. W przypadku generowania pojedynczych pakunków źródłowych, takie zachowanie jest prawdziwe tylko dla pakunku źródłowego oznakowania marką (patrz wyżej).

Dla wszystkich innych pakunków źródłowych zostanie skopiowana zawartość katalogu sourceTemplateBundle.