[ntk/apt.git] / vendor / README

The vendor system in APT is an experiment to help distributions ship a stock
apt release instead of applying documentation patches to it, increasing
maintenance burden for everyone and hiding 'interesting' patches in the mix.

The provided information is used in the apt-key script and in documentation
like manpages and example configuration files. If you have patches modifying
additional bits and pieces currently not covered by this system please
contact us so we can change this!


== Adding a new vendor

In the same directory you found this README in you should create a new
directory with the name of your distribution (as defined by dpkg-vendor,
 e.g. via "dpkg-vendor --query Vendor"). The name is case-insensitive,
but ensure that the name is otherwise correct and the other fields in
your deb-origin(5) file are correct as well as our buildsystem relies on
this information.

If no information is found for the current vendor at buildtime, the system
looks for a vendor the current vendor is a derivative of, falling back to
Debian if all else fails.

The directory should include 2 files at the moment. It is best to look
at the files of other distributions to understand what values are to be
expected. Some additional notes about them can be found below.

If we happen to include new fields/files in this system, we will opt for
using a sensible default rather than failing the build or similar, so
you are recommend to watch this space.
Ensure also that your information is up-to-date!

Contributing a new vendor as well as updating a existing one is best done
by opening a bug in the Debian BTS against apt with a patch attached.


== apt-vendor.ent

The format used is the one DocBook XML uses. The file is included as an
entity file in the manpages xml source, so the syntax has to be valid!

The keyring-* settings are additionally used also in the creation of the
apt-key script and the keyring-package in particular as a dependency for apt.

The field current-codename is optional and can be used in sources.list.in.


== sources.list.in

An example for a sources.list which will be shipped in /usr/share/doc.
This file will NOT be installed in /etc or otherwise used by apt.

You can use some placeholders in this file, namely:
* &debian-stable-codename;
* &debian-oldstable-codename;
* &debian-testing-codename;
* &ubuntu-codename;
with the value you would expect based on the name.

The placeholder &current-codename; is yours and can be set in apt-vendor.ent


== apt.conf-*

Files in your vendor directory following this naming scheme will be picked up
by the debian/rules file and installed in /etc/apt/apt.conf.d/ directory.
Commit	Line	Data
feb81787 DK	1	The vendor system in APT is an experiment to help distributions ship a stock
	2	apt release instead of applying documentation patches to it, increasing
	3	maintenance burden for everyone and hiding 'interesting' patches in the mix.
	4
	5	The provided information is used in the apt-key script and in documentation
	6	like manpages and example configuration files. If you have patches modifying
	7	additional bits and pieces currently not covered by this system please
	8	contact us so we can change this!
	9
	10
	11	== Adding a new vendor
	12
	13	In the same directory you found this README in you should create a new
	14	directory with the name of your distribution (as defined by dpkg-vendor,
	15	e.g. via "dpkg-vendor --query Vendor"). The name is case-insensitive,
	16	but ensure that the name is otherwise correct and the other fields in
	17	your deb-origin(5) file are correct as well as our buildsystem relies on
	18	this information.
	19
	20	If no information is found for the current vendor at buildtime, the system
	21	looks for a vendor the current vendor is a derivative of, falling back to
	22	Debian if all else fails.
	23
	24	The directory should include 2 files at the moment. It is best to look
	25	at the files of other distributions to understand what values are to be
	26	expected. Some additional notes about them can be found below.
	27
	28	If we happen to include new fields/files in this system, we will opt for
	29	using a sensible default rather than failing the build or similar, so
	30	you are recommend to watch this space.
	31	Ensure also that your information is up-to-date!
	32
	33	Contributing a new vendor as well as updating a existing one is best done
	34	by opening a bug in the Debian BTS against apt with a patch attached.
	35
	36
	37	== apt-vendor.ent
	38
	39	The format used is the one DocBook XML uses. The file is included as an
	40	entity file in the manpages xml source, so the syntax has to be valid!
	41
	42	The keyring-* settings are additionally used also in the creation of the
	43	apt-key script and the keyring-package in particular as a dependency for apt.
	44
	45	The field current-codename is optional and can be used in sources.list.in.
	46
	47
	48	== sources.list.in
	49
	50	An example for a sources.list which will be shipped in /usr/share/doc.
	51	This file will NOT be installed in /etc or otherwise used by apt.
	52
	53	You can use some placeholders in this file, namely:
	54	* &debian-stable-codename;
	55	* &debian-oldstable-codename;
	56	* &debian-testing-codename;
	57	* &ubuntu-codename;
	58	with the value you would expect based on the name.
	59
	60	The placeholder &current-codename; is yours and can be set in apt-vendor.ent
c1b3d189 DK	61
	62
	63	== apt.conf-*
	64
	65	Files in your vendor directory following this naming scheme will be picked up
	66	by the debian/rules file and installed in /etc/apt/apt.conf.d/ directory.