Whitespace-only fixes. Translators, please ignore.
This commit is contained in:
Warren Block
parent
15d408c4f4
commit
f99f3e141e
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=42408
1 changed files with 228 additions and 193 deletions
|
|
@ -13,7 +13,7 @@
|
|||
<surname>Kamp</surname>
|
||||
<contrib>Contributed by </contrib>
|
||||
</author>
|
||||
<author>
|
||||
<author>
|
||||
<firstname>Giorgos</firstname>
|
||||
<surname>Keramidas</surname>
|
||||
</author>
|
||||
|
|
@ -23,70 +23,76 @@
|
|||
|
||||
<title>Source Tree Guidelines and Policies</title>
|
||||
|
||||
<para>This chapter documents various guidelines and policies in force for
|
||||
the FreeBSD source tree.</para>
|
||||
<para>This chapter documents various guidelines and policies in
|
||||
force for the FreeBSD source tree.</para>
|
||||
|
||||
<sect1 id="policies-style">
|
||||
<title>Style Guidelines</title>
|
||||
|
||||
<indexterm><primary>style</primary></indexterm>
|
||||
|
||||
<para>Consistent coding style is extremely important, particularly
|
||||
with large projects like &os;. Code should follow the &os; coding
|
||||
styles described in &man.style.9; and
|
||||
with large projects like &os;. Code should follow the &os;
|
||||
coding styles described in &man.style.9; and
|
||||
&man.style.Makefile.5;.</para>
|
||||
</sect1>
|
||||
|
||||
<sect1 id="policies-maintainer">
|
||||
<title><makevar>MAINTAINER</makevar> on Makefiles</title>
|
||||
|
||||
<indexterm><primary>ports maintainer</primary></indexterm>
|
||||
|
||||
<para>If a particular portion of the &os; <filename>src/</filename>
|
||||
distribution is being maintained by a person or group of persons,
|
||||
this is communicated through an entry in the
|
||||
<filename>src/MAINTAINERS</filename> file. Maintainers of ports
|
||||
within the Ports Collection express their maintainership to the
|
||||
world by adding a <makevar>MAINTAINER</makevar> line to the
|
||||
<para>If a particular portion of the &os;
|
||||
<filename>src/</filename> distribution is being maintained by a
|
||||
person or group of persons, this is communicated through an
|
||||
entry in the <filename>src/MAINTAINERS</filename> file.
|
||||
Maintainers of ports within the Ports Collection express their
|
||||
maintainership to the world by adding a
|
||||
<makevar>MAINTAINER</makevar> line to the
|
||||
<filename>Makefile</filename> of the port in question:</para>
|
||||
|
||||
<programlisting><makevar>MAINTAINER</makevar>= <replaceable>email-addresses</replaceable></programlisting>
|
||||
|
||||
<tip>
|
||||
<para>For other parts of the repository, or for sections not listed
|
||||
as having a maintainer, or when you are unsure who the active
|
||||
maintainer is, try looking at the recent commit history of the
|
||||
relevant parts of the source tree. It is quite often the case
|
||||
that a maintainer is not explicitly named, but the people who are
|
||||
actively working in a part of the source tree for, say, the last
|
||||
couple of years are interested in reviewing changes. Even if this
|
||||
is not specifically mentioned in the documentation or the source
|
||||
itself, asking for a review as a form of courtesy is a very
|
||||
reasonable thing to do.</para>
|
||||
<para>For other parts of the repository, or for sections not
|
||||
listed as having a maintainer, or when you are unsure who the
|
||||
active maintainer is, try looking at the recent commit history
|
||||
of the relevant parts of the source tree. It is quite often
|
||||
the case that a maintainer is not explicitly named, but the
|
||||
people who are actively working in a part of the source tree
|
||||
for, say, the last couple of years are interested in reviewing
|
||||
changes. Even if this is not specifically mentioned in the
|
||||
documentation or the source itself, asking for a review as a
|
||||
form of courtesy is a very reasonable thing to do.</para>
|
||||
</tip>
|
||||
|
||||
<para>The role of the maintainer is as follows:</para>
|
||||
|
||||
<itemizedlist>
|
||||
<listitem>
|
||||
<para>The maintainer owns and is responsible for that code. This means
|
||||
that he or she is responsible for fixing bugs and answering problem reports
|
||||
pertaining to that piece of the code, and in the case of contributed
|
||||
software, for tracking new versions, as appropriate.</para>
|
||||
<para>The maintainer owns and is responsible for that code.
|
||||
This means that he or she is responsible for fixing bugs and
|
||||
answering problem reports pertaining to that piece of the
|
||||
code, and in the case of contributed software, for tracking
|
||||
new versions, as appropriate.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Changes to directories which have a maintainer defined shall be sent
|
||||
to the maintainer for review before being committed. Only if the
|
||||
maintainer does not respond for an unacceptable period of time, to
|
||||
several emails, will it be acceptable to commit changes without review
|
||||
by the maintainer. However, it is suggested that you try to have the
|
||||
changes reviewed by someone else if at all possible.</para>
|
||||
<para>Changes to directories which have a maintainer defined
|
||||
shall be sent to the maintainer for review before being
|
||||
committed. Only if the maintainer does not respond for an
|
||||
unacceptable period of time, to several emails, will it be
|
||||
acceptable to commit changes without review by the
|
||||
maintainer. However, it is suggested that you try to have
|
||||
the changes reviewed by someone else if at all
|
||||
possible.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>It is of course not acceptable to add a person or group as
|
||||
maintainer unless they agree to assume this duty. On the other hand it
|
||||
does not have to be a committer and it can easily be a group of
|
||||
people.</para>
|
||||
<para>It is of course not acceptable to add a person or group
|
||||
as maintainer unless they agree to assume this duty. On the
|
||||
other hand it does not have to be a committer and it can
|
||||
easily be a group of people.</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
</sect1>
|
||||
|
|
@ -115,37 +121,44 @@
|
|||
|
||||
<indexterm><primary>contributed software</primary></indexterm>
|
||||
|
||||
<para>Some parts of the FreeBSD distribution consist of software that is
|
||||
actively being maintained outside the FreeBSD project. For historical
|
||||
reasons, we call this <emphasis>contributed</emphasis> software. Some
|
||||
examples are <application>sendmail</application>, <application>gcc</application> and <application>patch</application>.</para>
|
||||
<para>Some parts of the FreeBSD distribution consist of software
|
||||
that is actively being maintained outside the FreeBSD project.
|
||||
For historical reasons, we call this
|
||||
<emphasis>contributed</emphasis> software. Some examples are
|
||||
<application>sendmail</application>,
|
||||
<application>gcc</application> and
|
||||
<application>patch</application>.</para>
|
||||
|
||||
<para>Over the last couple of years, various methods have been used in
|
||||
dealing with this type of software and all have some number of
|
||||
advantages and drawbacks. No clear winner has emerged.</para>
|
||||
<para>Over the last couple of years, various methods have been
|
||||
used in dealing with this type of software and all have some
|
||||
number of advantages and drawbacks. No clear winner has
|
||||
emerged.</para>
|
||||
|
||||
<para>Since this is the case, after some debate one of these methods has
|
||||
been selected as the <quote>official</quote> method and will be required
|
||||
for future imports of software of this kind. Furthermore, it is
|
||||
strongly suggested that existing contributed software converge on this
|
||||
model over time, as it has significant advantages over the old method,
|
||||
including the ability to easily obtain diffs relative to the
|
||||
<quote>official</quote> versions of the source by everyone (even without
|
||||
direct repository access). This will make it significantly easier to return changes
|
||||
to the primary developers of the contributed software.</para>
|
||||
<para>Since this is the case, after some debate one of these
|
||||
methods has been selected as the <quote>official</quote> method
|
||||
and will be required for future imports of software of this
|
||||
kind. Furthermore, it is strongly suggested that existing
|
||||
contributed software converge on this model over time, as it has
|
||||
significant advantages over the old method, including the
|
||||
ability to easily obtain diffs relative to the
|
||||
<quote>official</quote> versions of the source by everyone (even
|
||||
without direct repository access). This will make it
|
||||
significantly easier to return changes to the primary developers
|
||||
of the contributed software.</para>
|
||||
|
||||
<para>Ultimately, however, it comes down to the people actually doing the
|
||||
work. If using this model is particularly unsuited to the package being
|
||||
dealt with, exceptions to these rules may be granted only with the
|
||||
approval of the core team and with the general consensus of the other
|
||||
developers. The ability to maintain the package in the future will be a
|
||||
key issue in the decisions.</para>
|
||||
<para>Ultimately, however, it comes down to the people actually
|
||||
doing the work. If using this model is particularly unsuited to
|
||||
the package being dealt with, exceptions to these rules may be
|
||||
granted only with the approval of the core team and with the
|
||||
general consensus of the other developers. The ability to
|
||||
maintain the package in the future will be a key issue in the
|
||||
decisions.</para>
|
||||
|
||||
<note>
|
||||
<para>Because it makes it harder to import future versions
|
||||
minor, trivial and/or
|
||||
cosmetic changes are <emphasis>strongly discouraged</emphasis> on
|
||||
files that are still tracking the vendor branch.</para>
|
||||
minor, trivial and/or cosmetic changes are
|
||||
<emphasis>strongly discouraged</emphasis> on files that are
|
||||
still tracking the vendor branch.</para>
|
||||
</note>
|
||||
|
||||
<sect2 id="vendor-import-svn">
|
||||
|
|
@ -169,16 +182,16 @@
|
|||
|
||||
<para>If this is your first import after the switch to
|
||||
<acronym>SVN</acronym>, you will have to flatten and clean
|
||||
up the vendor tree, and bootstrap merge history in the main
|
||||
tree. If not, you can safely omit this step.</para>
|
||||
up the vendor tree, and bootstrap merge history in the
|
||||
main tree. If not, you can safely omit this step.</para>
|
||||
|
||||
<para>During the conversion from <acronym>CVS</acronym> to
|
||||
<acronym>SVN</acronym>, vendor branches were imported with
|
||||
the same layout as the main tree. For example, the
|
||||
<application>foo</application> vendor sources ended up in
|
||||
<filename>vendor/<replaceable>foo</replaceable>/dist/contrib/<replaceable>foo</replaceable></filename>,
|
||||
but it is pointless and rather inconvenient. What we really
|
||||
want is to have the vendor source directly in
|
||||
but it is pointless and rather inconvenient. What we
|
||||
really want is to have the vendor source directly in
|
||||
<filename>vendor/<replaceable>foo</replaceable>/dist</filename>,
|
||||
like this:</para>
|
||||
|
||||
|
|
@ -192,9 +205,9 @@
|
|||
<para>Note that, the <literal>propdel</literal> bit is
|
||||
necessary because starting with 1.5, Subversion will
|
||||
automatically add <literal>svn:mergeinfo</literal> to any
|
||||
directory you copy or move. In this case, you will not need
|
||||
this information, since you are not going to merge anything
|
||||
from the tree you deleted.</para>
|
||||
directory you copy or move. In this case, you will not
|
||||
need this information, since you are not going to merge
|
||||
anything from the tree you deleted.</para>
|
||||
|
||||
<note>
|
||||
<para>You may want to flatten the tags as well. The
|
||||
|
|
@ -202,19 +215,19 @@
|
|||
the commit until the end.</para>
|
||||
</note>
|
||||
|
||||
<para>Check the <filename>dist</filename> tree and perform any
|
||||
cleanup that is deemed to be necessary. You may want to
|
||||
disable keyword expansion, as it makes no sense on
|
||||
<para>Check the <filename>dist</filename> tree and perform
|
||||
any cleanup that is deemed to be necessary. You may want
|
||||
to disable keyword expansion, as it makes no sense on
|
||||
unmodified vendor code. In some cases, it can be even be
|
||||
harmful.</para>
|
||||
|
||||
<screen>&prompt.user; <userinput><command>svn propdel</command> svn:keywords <option>-R</option> <filename>.</filename></userinput>
|
||||
&prompt.user; <userinput><command>svn commit</command></userinput></screen>
|
||||
|
||||
<para>Bootstrapping of <literal>svn:mergeinfo</literal> on the
|
||||
target directory (in the main tree) to the revision that
|
||||
corresponds to the last change was made to the vendor tree
|
||||
prior to importing new sources is also needed:</para>
|
||||
<para>Bootstrapping of <literal>svn:mergeinfo</literal> on
|
||||
the target directory (in the main tree) to the revision
|
||||
that corresponds to the last change was made to the vendor
|
||||
tree prior to importing new sources is also needed:</para>
|
||||
|
||||
<screen>&prompt.user; <userinput><command>cd</command> <filename>head/contrib/<replaceable>foo</replaceable></filename></userinput>
|
||||
&prompt.user; <userinput><command>svn merge</command> <option>--record-only</option> <replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/dist@<replaceable>12345678</replaceable> <filename>.</filename></userinput>
|
||||
|
|
@ -228,16 +241,17 @@
|
|||
<step>
|
||||
<title>Importing New Sources</title>
|
||||
|
||||
<para>Prepare a full, clean tree of the vendor sources. With
|
||||
<acronym>SVN</acronym>, we can keep a full distribution in
|
||||
the vendor tree without bloating the main tree. Import
|
||||
everything but merge only what is needed.</para>
|
||||
<para>Prepare a full, clean tree of the vendor sources.
|
||||
With <acronym>SVN</acronym>, we can keep a full
|
||||
distribution in the vendor tree without bloating the main
|
||||
tree. Import everything but merge only what is
|
||||
needed.</para>
|
||||
|
||||
<para>Note that you will need to add any files that were added
|
||||
since the last vendor import, and remove any that were
|
||||
removed. To facilitate this, you should prepare sorted
|
||||
lists of the contents of the vendor tree and of the sources
|
||||
you are about to import:</para>
|
||||
<para>Note that you will need to add any files that were
|
||||
added since the last vendor import, and remove any that
|
||||
were removed. To facilitate this, you should prepare
|
||||
sorted lists of the contents of the vendor tree and of the
|
||||
sources you are about to import:</para>
|
||||
|
||||
<screen>&prompt.user; <userinput><command>cd</command> <filename>vendor/<replaceable>foo</replaceable>/dist</filename></userinput>
|
||||
&prompt.user; <userinput><command>svn list</command> <option>-R</option> | <command>grep</command> <option>-v</option> '/$' | <command>sort</command> > <filename>../<replaceable>old</replaceable></filename></userinput>
|
||||
|
|
@ -265,11 +279,11 @@
|
|||
&prompt.user; <userinput><command>comm</command> <option>-13</option> <filename>../<replaceable>old</replaceable></filename> <filename>../<replaceable>new</replaceable></filename> | <command>xargs</command> svn add</userinput></screen>
|
||||
|
||||
<warning>
|
||||
<para>If there are new directories in the new distribution,
|
||||
the last command will fail. You will have to add the
|
||||
directories, and run it again. Conversely, if any
|
||||
directories were removed, you will have to remove them
|
||||
manually.</para>
|
||||
<para>If there are new directories in the new
|
||||
distribution, the last command will fail. You will have
|
||||
to add the directories, and run it again. Conversely,
|
||||
if any directories were removed, you will have to remove
|
||||
them manually.</para>
|
||||
</warning>
|
||||
|
||||
<para>Check properties on any new files:</para>
|
||||
|
|
@ -302,8 +316,9 @@
|
|||
|
||||
<note>
|
||||
<para>You are ready to commit, but you should first check
|
||||
the output of <command>svn stat</command> and <command>svn
|
||||
diff</command> to make sure everything is in order.</para>
|
||||
the output of <command>svn stat</command> and
|
||||
<command>svn diff</command> to make sure everything is
|
||||
in order.</para>
|
||||
</note>
|
||||
|
||||
<para>Once you have committed the new vendor release, you
|
||||
|
|
@ -312,12 +327,13 @@
|
|||
|
||||
<screen>&prompt.user; <userinput><command>svn copy</command> <filename><replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/dist</filename> <filename><replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/<replaceable>9.9</replaceable></filename></userinput></screen>
|
||||
|
||||
<para>To get the new tag, you can update your working copy of
|
||||
<para>To get the new tag, you can update your working copy
|
||||
of
|
||||
<filename>vendor/<replaceable>foo</replaceable></filename>.</para>
|
||||
|
||||
<note>
|
||||
<para>If you choose to do the copy in the checkout instead,
|
||||
do not forget to remove the generated
|
||||
<para>If you choose to do the copy in the checkout
|
||||
instead, do not forget to remove the generated
|
||||
<literal>svn:mergeinfo</literal> as described
|
||||
above.</para>
|
||||
</note>
|
||||
|
|
@ -335,10 +351,11 @@
|
|||
&prompt.user; <userinput><command>svn update</command></userinput>
|
||||
&prompt.user; <userinput><command>svn merge</command> <option>--accept=postpone</option> <filename><replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/dist</filename></userinput></screen>
|
||||
|
||||
<para>Resolve any conflicts, and make sure that any files that
|
||||
were added or removed in the vendor tree have been properly
|
||||
added or removed in the main tree. It is always a good idea
|
||||
to check differences against the vendor branch:</para>
|
||||
<para>Resolve any conflicts, and make sure that any files
|
||||
that were added or removed in the vendor tree have been
|
||||
properly added or removed in the main tree. It is always
|
||||
a good idea to check differences against the vendor
|
||||
branch:</para>
|
||||
|
||||
<screen>&prompt.user; <userinput><command>svn diff</command> <option>--no-diff-deleted</option> <option>--old=</option><filename><replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/dist</filename> <option>--new=</option><filename>.</filename></userinput></screen>
|
||||
|
||||
|
|
@ -347,16 +364,16 @@
|
|||
vendor tree but not in the main tree.</para>
|
||||
|
||||
<note>
|
||||
<para>With <acronym>SVN</acronym>, there is no concept of on
|
||||
or off the vendor branch. If a file that previously had
|
||||
local modifications no longer does, just remove any
|
||||
<para>With <acronym>SVN</acronym>, there is no concept of
|
||||
on or off the vendor branch. If a file that previously
|
||||
had local modifications no longer does, just remove any
|
||||
left-over cruft, such as &os; version tags, so it no
|
||||
longer shows up in diffs against the vendor tree.</para>
|
||||
</note>
|
||||
|
||||
<para>If any changes are required for the world to build with
|
||||
the new sources, make them now — and test until you
|
||||
are satisfied that everything build and runs
|
||||
<para>If any changes are required for the world to build
|
||||
with the new sources, make them now — and test until
|
||||
you are satisfied that everything build and runs
|
||||
correctly.</para>
|
||||
</step>
|
||||
|
||||
|
|
@ -378,93 +395,103 @@
|
|||
<sect1 id="policies-encumbered">
|
||||
<title>Encumbered Files</title>
|
||||
|
||||
<para>It might occasionally be necessary to include an encumbered file in
|
||||
the FreeBSD source tree. For example, if a device requires a small
|
||||
piece of binary code to be loaded to it before the device will operate,
|
||||
and we do not have the source to that code, then the binary file is said
|
||||
to be encumbered. The following policies apply to including encumbered
|
||||
files in the FreeBSD source tree.</para>
|
||||
<para>It might occasionally be necessary to include an encumbered
|
||||
file in the FreeBSD source tree. For example, if a device
|
||||
requires a small piece of binary code to be loaded to it before
|
||||
the device will operate, and we do not have the source to that
|
||||
code, then the binary file is said to be encumbered. The
|
||||
following policies apply to including encumbered files in the
|
||||
FreeBSD source tree.</para>
|
||||
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>Any file which is interpreted or executed by the system CPU(s)
|
||||
and not in source format is encumbered.</para>
|
||||
<para>Any file which is interpreted or executed by the system
|
||||
CPU(s) and not in source format is encumbered.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Any file with a license more restrictive than BSD or GNU is
|
||||
encumbered.</para>
|
||||
<para>Any file with a license more restrictive than BSD or GNU
|
||||
is encumbered.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>A file which contains downloadable binary data for use by the
|
||||
hardware is not encumbered, unless (1) or (2) apply to it. It must
|
||||
be stored in an architecture neutral ASCII format (file2c or
|
||||
uuencoding is recommended).</para>
|
||||
<para>A file which contains downloadable binary data for use
|
||||
by the hardware is not encumbered, unless (1) or (2) apply
|
||||
to it. It must be stored in an architecture neutral ASCII
|
||||
format (file2c or uuencoding is recommended).</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Any encumbered file requires specific approval from the
|
||||
<ulink url="&url.base;/administration.html#t-core">Core Team</ulink> before it is added to the
|
||||
repository.</para>
|
||||
<para>Any encumbered file requires specific approval from the
|
||||
<ulink url="&url.base;/administration.html#t-core">Core
|
||||
Team</ulink> before it is added to the repository.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Encumbered files go in <filename>src/contrib</filename> or
|
||||
<filename>src/sys/contrib</filename>.</para>
|
||||
<para>Encumbered files go in <filename>src/contrib</filename>
|
||||
or <filename>src/sys/contrib</filename>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>The entire module should be kept together. There is no point in
|
||||
splitting it, unless there is code-sharing with non-encumbered
|
||||
code.</para>
|
||||
<para>The entire module should be kept together. There is no
|
||||
point in splitting it, unless there is code-sharing with
|
||||
non-encumbered code.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Object files are named
|
||||
<para>Object files are named
|
||||
<filename><replaceable>arch</replaceable>/<replaceable>filename</replaceable>.o.uu></filename>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Kernel files:</para>
|
||||
<para>Kernel files:</para>
|
||||
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>Should always be referenced in
|
||||
<filename>conf/files.*</filename> (for build simplicity).</para>
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>Should always be referenced in
|
||||
<filename>conf/files.*</filename> (for build
|
||||
simplicity).</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>Should always be in <filename>LINT</filename>, but the
|
||||
<ulink url="&url.base;/administration.html#t-core">Core Team</ulink> decides per case if it
|
||||
should be commented out or not. The
|
||||
<ulink url="&url.base;/administration.html#t-core">Core Team</ulink> can, of course, change
|
||||
their minds later on.</para>
|
||||
</listitem>
|
||||
<listitem>
|
||||
<para>Should always be in <filename>LINT</filename>, but
|
||||
the <ulink
|
||||
url="&url.base;/administration.html#t-core">Core
|
||||
Team</ulink> decides per case if it should be
|
||||
commented out or not. The <ulink
|
||||
url="&url.base;/administration.html#t-core">Core
|
||||
Team</ulink> can, of course, change their minds later
|
||||
on.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>The <firstterm>Release Engineer</firstterm>
|
||||
decides whether or not it goes into the release.</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
<listitem>
|
||||
<para>The <firstterm>Release Engineer</firstterm>
|
||||
decides whether or not it goes into the release.</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>User-land files:</para>
|
||||
<para>User-land files:</para>
|
||||
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>The <ulink url="&url.base;/administration.html#t-core">Core team</ulink><indexterm>
|
||||
<primary>core team</primary></indexterm> decides if
|
||||
the code should be part of <command>make world</command>.</para>
|
||||
</listitem>
|
||||
<orderedlist>
|
||||
<listitem>
|
||||
<para>The <ulink
|
||||
url="&url.base;/administration.html#t-core">Core
|
||||
team</ulink><indexterm><primary>core
|
||||
team</primary></indexterm> decides if
|
||||
the code should be part of
|
||||
<command>make world</command>.</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>The <ulink url="&url.base;/administration.html#t-re">Release Engineering</ulink><indexterm>
|
||||
<primary>release engineering</primary></indexterm>
|
||||
decides if it goes into the release.</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
<listitem>
|
||||
<para>The <ulink
|
||||
url="&url.base;/administration.html#t-re">Release
|
||||
Engineering</ulink><indexterm><primary>release
|
||||
engineering</primary></indexterm>
|
||||
decides if it goes into the release.</para>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
</listitem>
|
||||
</orderedlist>
|
||||
</sect1>
|
||||
|
|
@ -491,10 +518,11 @@
|
|||
|
||||
<title>Shared Libraries</title>
|
||||
|
||||
<para>If you are adding shared library support to a port or other piece of
|
||||
software that does not have one, the version numbers should follow these
|
||||
rules. Generally, the resulting numbers will have nothing to do with
|
||||
the release version of the software.</para>
|
||||
<para>If you are adding shared library support to a port or other
|
||||
piece of software that does not have one, the version numbers
|
||||
should follow these rules. Generally, the resulting numbers
|
||||
will have nothing to do with the release version of the
|
||||
software.</para>
|
||||
|
||||
<para>The three principles of shared library building are:</para>
|
||||
|
||||
|
|
@ -504,57 +532,64 @@
|
|||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>If there is a change that is backwards compatible, bump minor
|
||||
number (note that ELF systems ignore the minor number)</para>
|
||||
<para>If there is a change that is backwards compatible, bump
|
||||
minor number (note that ELF systems ignore the minor
|
||||
number)</para>
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
<para>If there is an incompatible change, bump major number</para>
|
||||
<para>If there is an incompatible change, bump major
|
||||
number</para>
|
||||
</listitem>
|
||||
</itemizedlist>
|
||||
|
||||
<para>For instance, added functions and bugfixes result in the minor
|
||||
version number being bumped, while deleted functions, changed function
|
||||
call syntax, etc. will force the major version number to change.</para>
|
||||
<para>For instance, added functions and bugfixes result in the
|
||||
minor version number being bumped, while deleted functions,
|
||||
changed function call syntax, etc. will force the major version
|
||||
number to change.</para>
|
||||
|
||||
<para>Stick to version numbers of the form major.minor
|
||||
(<replaceable>x</replaceable>.<replaceable>y</replaceable>). Our a.out
|
||||
dynamic linker does not handle version numbers of the form
|
||||
(<replaceable>x</replaceable>.<replaceable>y</replaceable>).
|
||||
Our a.out dynamic linker does not handle version numbers of the
|
||||
form
|
||||
<replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable>
|
||||
well. Any version number after the <replaceable>y</replaceable>
|
||||
(i.e. the third digit) is totally ignored when comparing shared lib
|
||||
version numbers to decide which library to link with. Given two shared
|
||||
libraries that differ only in the <quote>micro</quote> revision,
|
||||
<command>ld.so</command> will link with the higher one. That is, if you link
|
||||
with <filename>libfoo.so.3.3.3</filename>, the linker only records
|
||||
<literal>3.3</literal> in the headers, and will link with anything
|
||||
starting with
|
||||
<replaceable>libfoo.so.3</replaceable>.<replaceable>(anything >=
|
||||
3)</replaceable>.<replaceable>(highest
|
||||
(i.e. the third digit) is totally ignored when comparing shared
|
||||
lib version numbers to decide which library to link with. Given
|
||||
two shared libraries that differ only in the
|
||||
<quote>micro</quote> revision, <command>ld.so</command> will
|
||||
link with the higher one. That is, if you link with
|
||||
<filename>libfoo.so.3.3.3</filename>, the linker only records
|
||||
<literal>3.3</literal> in the headers, and will link with
|
||||
anything starting with
|
||||
<replaceable>libfoo.so.3</replaceable>.<replaceable>(anything
|
||||
>= 3)</replaceable>.<replaceable>(highest
|
||||
available)</replaceable>.</para>
|
||||
|
||||
<note>
|
||||
<para><command>ld.so</command> will always use the highest
|
||||
<quote>minor</quote> revision. For instance, it will use
|
||||
<filename>libc.so.2.2</filename> in preference to
|
||||
<filename>libc.so.2.0</filename>, even if the program was initially
|
||||
linked with <filename>libc.so.2.0</filename>.</para>
|
||||
<filename>libc.so.2.0</filename>, even if the program was
|
||||
initially linked with <filename>libc.so.2.0</filename>.</para>
|
||||
</note>
|
||||
|
||||
<para>In addition, our ELF dynamic linker does not handle minor version
|
||||
numbers at all. However, one should still specify a major and minor
|
||||
version number as our <filename>Makefile</filename>s <quote>do the right thing</quote>
|
||||
based on the type of system.</para>
|
||||
<para>In addition, our ELF dynamic linker does not handle minor
|
||||
version numbers at all. However, one should still specify a
|
||||
major and minor version number as our
|
||||
<filename>Makefile</filename>s <quote>do the right thing</quote>
|
||||
based on the type of system.</para>
|
||||
|
||||
<para>For non-port libraries, it is also our policy to change the shared
|
||||
library version number only once between releases. In addition, it is
|
||||
our policy to change the major shared library version number only once
|
||||
between major OS releases (i.e. from 6.0 to 7.0). When you make a
|
||||
change to a system library that requires the version number to be
|
||||
bumped, check the <filename>Makefile</filename>'s commit logs. It is the
|
||||
responsibility of the committer to ensure that the first such change
|
||||
since the release will result in the shared library version number in
|
||||
the <filename>Makefile</filename> to be updated, and any subsequent
|
||||
changes will not.</para>
|
||||
<para>For non-port libraries, it is also our policy to change the
|
||||
shared library version number only once between releases. In
|
||||
addition, it is our policy to change the major shared library
|
||||
version number only once between major OS releases (i.e. from
|
||||
6.0 to 7.0). When you make a change to a system library that
|
||||
requires the version number to be bumped, check the
|
||||
<filename>Makefile</filename>'s commit logs. It is the
|
||||
responsibility of the committer to ensure that the first such
|
||||
change since the release will result in the shared library
|
||||
version number in the <filename>Makefile</filename> to be
|
||||
updated, and any subsequent changes will not.</para>
|
||||
</sect1>
|
||||
</chapter>
|
||||
|
|
|
|||
Loading…
Reference in a new issue