[Blends-commit] [SCM] blends-dev branch, master, updated. ab1dc6fe5a4b9c5b28988dfe274a023083359748
Emmanouil Kiagias
e.kiagias at gmail.com
Tue Sep 17 17:46:46 UTC 2013
The following commit has been merged in the master branch:
commit ab1dc6fe5a4b9c5b28988dfe274a023083359748
Author: Emmanouil Kiagias <e.kiagias at gmail.com>
Date: Tue Sep 17 19:45:08 2013 +0200
updated blends/doc/en/A_devel.sgml, blends-gsoc first documentation
diff --git a/doc/en/A_devel.sgml b/doc/en/A_devel.sgml
index 88ecdac..da63841 100644
--- a/doc/en/A_devel.sgml
+++ b/doc/en/A_devel.sgml
@@ -22,17 +22,37 @@ depend. This <package><var><blend></var>-config</package> package
instantiates the <var>Blend</var> in the common registry for all Blends in
<file>/etc/blends</file>.
</p>
+
+<p>
+The version <package>0.7.0</package> of <package>blends-dev</package> uses
+<url id="https://wiki.debian.org/UltimateDebianDatabase" name="UDD">
+to generate Blends' metapackages. Currently all Blends' info is stored into UDD.
+Information such as VCs, description, homepage etc for a Blend can be found into the
+<url id="http://udd.debian.org/schema/udd.html#public.table.blends-metadata" name="blends_metadata">
+UDD table. All the info about Blends' tasks and their package dependencies are also stored
+into the <url id="http://udd.debian.org/schema/udd.html#public.table.blends-tasks" name="blends_tasks"> and
+<url id="http://udd.debian.org/schema/udd.html#public.table.blends-dependencies-alternatives" name="blends_dependencies_alternatives">
+tables. Having the latter in combination with other UDD tables
+(such as a table with info about all Debian available packages)
+provides the ability to check whether a package exists for an architecture or not thus
+<package>blends-dev</package> can generate architecture dependent metapackages.
+</p>
+
<p>
The best idea to use the tools provided by the
<package>blends-dev</package> is to put a <file>Makefile</file> into the
-build directory containig one single line
+build directory containing one single line
<example>
include /usr/share/blends-dev/Makefile
</example>
-(see <file>/usr/share/doc/blends-dev/examples/Makefile</file>). Using
-this <file>Makefile</file> all tools that were contained in
+(see <file>/usr/share/doc/blends-dev/examples/Makefile</file>).
+Users using <package>blends-dev 0.7.0</package> on existing Blends
+which have more than one releases might encouter some <file>Makefile</file>
+errors for more info see <ref id="statusdump"> and <ref id="changelogentry">.
+
+Using this <file>Makefile</file> all tools that were contained in
<package>blends-dev</package> package versions before 0.4. These tools
are moved to <file>/usr/share/blends-dev/</file> because there is no need
to call them directly. Here is a list of the <file>make</file> targets.
@@ -42,12 +62,26 @@ to call them directly. Here is a list of the <file>make</file> targets.
<heading>Blend<tt>-tasks.desk</tt></heading>
<p>
-This target is the description file that is used in
-<prgn>tasksel</prgn> to enable selecting the tasks belonging to the
-Blend. The file will be moved to the
-<var>blend</var><package>-tasks</package>. All information is obtained
-from the single task files in the <file>tasks</file> directory of the
-Blend source.
+This target generates a <package>task-description.template</package> file.
+The template can be converted to a proper description file that is used in
+<prgn>tasksel</prgn> to enable selecting the tasks belonging to the Blend.
+The initial template contains all the needed package dependencies
+for a Blend. But because some packages might not be available for a(or multiple)
+architectures the template uses the following syntax when specifying packages:
+<example> package1 [!arch1 arch2]</example>
+
+That says do not include the package1 in the
+taskdescription file when arch1 or arch2 is used.
+When a Blends' <package>orig.tar.gz</package> is generated,
+the initial template gets converted
+from the <package>blends-dev rules</package> file to a proper taskdescription file.
+The convertion is filtering out the packages which are not available for the
+host's (where the <package>orig.tar.gz</package> is generated) architecture.
+This make sure that the taskdescription file will not include package which are
+not available for the target architecture.
+Finally the file will be moved to the
+<var>blend</var><package>-tasks</package>. All information
+about Blends package dependencies is obtained from the UDD.
</p>
</sect1>
@@ -62,15 +96,37 @@ enhance flexibility about changes inside the Debian package pool where
new packages might appear and others might be renamed.
The <file>tasks</file> just define which dependencies the Blend
maintainer group wants to be fulfilled and the
-script <prgn>blend-gen-control</prgn> verifies whether these
-dependencies exist in the specified package pool and create
-the <file>debian/control</file> file according to the available
-packages. This does not only work for the Debian package pool
+script <prgn>blend-gen-control</prgn> using UDD verifies whether these
+dependencies exist in a specified package pool. A
+package pool can be considered as the packages available for a
+combination of distribution, component and release values. By default when
+creating metapackages debian,main,testing values are used to "create" a package pool from UDD.
+Once a Blends' dependencies are verified the <file>debian/control</file> file is generated
+according to the available packages. This does not only work for the Debian package pool
containing the distributions stable, testing and unstable. You can
even build your metapackages against a different package pool of a
Debian based distribution. This is for instance used to create the
SkoleLinux metapackages.
</p>
+
+<p>
+As mentioned in the previous section, using UDD in Blends' tools provides the ability to generate
+architecture dependent metapackages. Thus the generated
+<package>debian/control</package> specifies for every task source target as architecture value:
+<example>Architecture: any</example>
+
+Specifying <package>any</package> indicates that the source package isn't dependent
+on any particular architecture and should compile fine on any one. To fulfil this
+in case of missing packages <package>control</package> file uses the following syntax:
+
+<example>Depends: package1 [!arch1 !arch2]</example>
+
+If a package is not available for a specific arch, exclude it from it. So the above example says:
+depend on package1 but not when architecture arch1 or arch2 is used. More info about
+<package>debian/control</package> syntax can be found in
+<url id="http://www.debian.org/doc/debian-policy/" name="Debian Policy Manual" >
+</p>
+
<p>
The syntax of the <file>tasks</file> files which serve as the central
database for the information in the <file>debian/control</file> file
@@ -115,7 +171,9 @@ influence the creation of the <file>debian/control</file> file are given.
the <file>debian/control</file> file inside the meta
package source archive any "Depends" or "Recommends" are
turned into "Suggests" to enable a flawless installation
- of the metapackage. Packages that are specified with
+ of the metapackage. Generally packages are concerned as missing if
+ they do not exist into Debian main component(default is testing release).
+ Packages that are specified with
"Suggests" will not be taken over to
the <prgn>tasksel</prgn> control file
(Blend<file>-tasks.desk</file>,
@@ -149,6 +207,89 @@ influence the creation of the <file>debian/control</file> file are given.
</p>
</sect1>
+<sect1 id="statusdump">
+ <heading><tt>statusdump</tt></heading>
+
+<p>
+This target generates a json file containing the latest package dependencies
+for the selected Blend. It parses the files from the <tt>tasks</tt> directory
+and generates a <var>blend</var><tt>_version.json</tt> into a <tt>dependency_data</tt>
+directory. As <tt>version</tt> it gets the latest version specified in the Blend's
+<tt>debian/changelog</tt> file. In case the <tt>dependency_data</tt> directory
+does not exist into a Blend's root directory it automatically creates it.
+</p>
+
+<p>
+A user can also generate a json dependencies file manually
+using the <tt>tasks_diff</tt> script. The script can be called
+from a Blend's root directory:
+
+<example>
+ /usr/share/blends-dev/task_diff --status-dump --tasks . --output blend_version.json
+</example>
+If the user does not specify the output argument the script by default
+will generate the json file under the <tt>tasks.json</tt> name in the
+current directory.
+</p>
+
+<p>
+Note: in case a user needs to generate a json file for a previous release
+(rather than the latest) to get the <tt>changelogentry</tt>
+(see <ref id="changelogentry">) target to work, must keep the following thing in mind:
+
+The user must provide to <tt>task_diff</tt> script the <em>root</em> directory of a previous Blend release
+(through the --task(-t) argument). He should also save the output into the <tt>dependency_data</tt>
+directory into the latest Blend release providing manually
+the name <var>blend</var><tt>_version.json</tt> (through the --output(-o) argument:
+
+<example>
+/usr/share/blends-dev/task_diff --status-dump -t blend/tags/previous/ -o latest_blend/dependency_data/blend_version.json
+</example>
+
+For example if the name of the Blend is <tt>myblend</tt> and the release is <tt>0.2.0</tt>
+then the json file must have the name <tt>myblend_0.2.0.json</tt>
+</p>
+
+</sect1>
+
+<sect1 id="changelogentry">
+ <heading>changelogentry</heading>
+
+<p>
+This target compares the latest and the previous Blend release and dumps the tasks'
+package differences. It reports the added/removed packages
+per task (or added/removed task files)
+between releases. This "report" is automatically
+added into the <tt>debian/changelog</tt>
+in the latest relase section under the file's manual changes.
+In case a previous difference report
+exists, it overrides it. In case a Blend does not have more than release
+(initial release) then this target is ignored.
+</p>
+
+<p>
+In order the comparison to be properly performed the
+<var>blend</var><tt>_version.json</tt> files for the two latest releases
+must exist under the <tt>dependency_data</tt> directory. In case any of the
+previous files is missing then the target will fail with an error
+(specifying the missing version_file). The json file for the latest
+release is automatically generated from the <tt>statusdump</tt> target
+so it this will not cause the problem.
+</p>
+
+<p>
+This changelog entry is a new feature so the problem of this target failing
+(because of a missing json file) will appear for existing Blends which have
+more than one releases and do not have a <var>blend</var><tt>_version.json</tt>
+for the previous release under their <tt>dependency_data</tt> directory.
+Usually Blend's releases are tagged into the VCs, so the previous problem
+can be solved by generating the dependency json file for the previous
+release (using a previous VCs tag). This can be done by calling manually
+the <tt>task_diff</tt> script (see <ref id="statusdump">)
+</p>
+
+</sect1>
+
<sect1>
<heading>Apt <file>sources.list</file> files in <file>/etc/blends/</file></heading>
<p>
--
Git repository for blends code
More information about the Blends-commit
mailing list