Clarify wording in the ports section of the Handbook.
The presentation assumes more knowledge on the part of a new user to FreeBSD than it should. Some of the text, while correct, is still too easy to misunderstand. The overall sense of the text does not change. Add note about ports not running their startup scripts upon installation as being by design. Submitted by: linimon Reviewed by: wblock Approved by: wblock (mentor) Differential Revision: https://reviews.freebsd.org/D8838
This commit is contained in:
Mark Linimon
parent
fae3847ad5
commit
c5261d8fda
Notes:
svn2git
2020-12-08 03:00:23 +00:00
svn path=/head/; revision=49827
1 changed files with 77 additions and 48 deletions
|
|
@ -70,8 +70,8 @@
|
|||
|
||||
<step>
|
||||
<para>Unpack the software from its distribution format. This
|
||||
is typically a tarball compressed with &man.compress.1;,
|
||||
&man.gzip.1;, or &man.bzip2.1;.</para>
|
||||
is typically a tarball compressed with a program such as
|
||||
&man.compress.1;, &man.gzip.1;, &man.bzip2.1; or &man.xz.1;.</para>
|
||||
</step>
|
||||
|
||||
<step>
|
||||
|
|
@ -400,11 +400,18 @@ Info: Lists information about open files (similar to fstat(1))</screen>
|
|||
offering many features that make dealing with binary packages
|
||||
faster and easier.</para>
|
||||
|
||||
<para><application>pkg</application> is not a replacement for
|
||||
port management tools like
|
||||
<package>ports-mgmt/portmaster</package> or
|
||||
<package>ports-mgmt/portupgrade</package>. These tools can be
|
||||
used to install third-party software from both binary packages
|
||||
<para>For sites wishing to only use prebuilt binary packages
|
||||
from the &os; mirrors, managing packages with
|
||||
<application>pkg</application> can be sufficient.</para>
|
||||
|
||||
<para>However, for those sites building from source or using
|
||||
their own repositories, a separate
|
||||
<emphasis>port management tool</emphasis> will be needed.</para>
|
||||
|
||||
<para>Since <application>pkg</application> only works with
|
||||
binary packages, it
|
||||
is not a replacement for such tools. Those tools can be
|
||||
used to install software from both binary packages
|
||||
and the Ports Collection, while
|
||||
<application>pkg</application> installs only binary
|
||||
packages.</para>
|
||||
|
|
@ -414,25 +421,36 @@ Info: Lists information about open files (similar to fstat(1))</screen>
|
|||
<application>pkg</application></title>
|
||||
|
||||
<para>&os; includes a bootstrap utility which can be used to
|
||||
download and install <application>pkg</application>, along
|
||||
with its manual pages.</para>
|
||||
download and install <application>pkg</application>
|
||||
and its manual pages. This utility is designed to work
|
||||
with versions of &os; starting with
|
||||
10.<replaceable>X</replaceable>.</para>
|
||||
|
||||
<note>
|
||||
<para>Not all &os; versions and architectures
|
||||
support this bootstrap process. The current list is at
|
||||
<link xlink:href="http://pkg.freebsd.org/"></link>.
|
||||
For other cases,
|
||||
<application>pkg</application> must instead be installed
|
||||
from the Ports Collection or as a binary package.</para>
|
||||
|
||||
</note>
|
||||
|
||||
<para>To bootstrap the system, run:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>/usr/sbin/pkg</userinput></screen>
|
||||
|
||||
<para>For earlier &os; versions,
|
||||
<application>pkg</application> must instead be installed
|
||||
from the Ports Collection or as a binary package.</para>
|
||||
<para>You must have a working Internet connection for the
|
||||
bootstrap process to suceed.</para>
|
||||
|
||||
<para>To install the port, run:</para>
|
||||
<para>Otherwise, to install the port, run:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>cd /usr/ports/ports-mgmt/pkg</userinput>
|
||||
&prompt.root; <userinput>make</userinput>
|
||||
&prompt.root; <userinput>make install clean</userinput></screen>
|
||||
|
||||
<para>When upgrading an existing system that originally used the
|
||||
older package system, the database must be converted to the
|
||||
older pkg_* tools, the database must be converted to the
|
||||
new format, so that the new tools are aware of the already
|
||||
installed packages. Once <application>pkg</application> has
|
||||
been installed, the
|
||||
|
|
@ -456,23 +474,25 @@ Info: Lists information about open files (similar to fstat(1))</screen>
|
|||
<para>The package database conversion may emit errors as the
|
||||
contents are converted to the new version. Generally, these
|
||||
errors can be safely ignored. However, a list of
|
||||
third-party software that was not successfully converted
|
||||
will be listed after <command>pkg2ng</command> has finished
|
||||
and these applications must be manually reinstalled.</para>
|
||||
software that was not successfully converted
|
||||
is shown after <command>pkg2ng</command> finishes.
|
||||
These applications must be manually reinstalled.</para>
|
||||
</note>
|
||||
|
||||
<para>To ensure that the &os; Ports Collection registers
|
||||
new software with <application>pkg</application>, and not
|
||||
the traditional packages format, &os; versions earlier than
|
||||
<para>To ensure that the Ports Collection registers
|
||||
new software with <application>pkg</application> instead of
|
||||
the traditional packages database, &os; versions earlier than
|
||||
10.<replaceable>X</replaceable> require this line in
|
||||
<filename>/etc/make.conf</filename>:</para>
|
||||
|
||||
<programlisting>WITH_PKGNG= yes</programlisting>
|
||||
|
||||
<para>By default <application>pkg</application> uses the &os;
|
||||
package mirrors. For information about building a custom
|
||||
package repository, see <xref
|
||||
linkend="ports-poudriere"/></para>
|
||||
<para>By default, <application>pkg</application> uses the
|
||||
binary packages from the &os;
|
||||
package mirrors (the <emphasis>repository</emphasis>).
|
||||
For information about building a custom
|
||||
package repository, see
|
||||
<xref linkend="ports-poudriere"/>.</para>
|
||||
|
||||
<para>Additional <application>pkg</application> configuration
|
||||
options are described in &man.pkg.conf.5;.</para>
|
||||
|
|
@ -589,7 +609,7 @@ Proceed with deleting packages [y/N]: <userinput>y</userinput>
|
|||
<sect2 xml:id="pkgng-auditing">
|
||||
<title>Auditing Installed Packages</title>
|
||||
|
||||
<para>Occasionally, software vulnerabilities may be discovered
|
||||
<para>Software vulnerabilities are regularly discovered
|
||||
in third-party applications. To address this,
|
||||
<application>pkg</application> includes a built-in auditing
|
||||
mechanism. To determine if there are any known
|
||||
|
|
@ -1152,7 +1172,8 @@ The deinstallation will free 229 kB
|
|||
|
||||
<para><package>ports-mgmt/portmaster</package> is a very
|
||||
small utility for upgrading installed ports.
|
||||
It is designed to use the tools installed with &os;
|
||||
It is designed to use the tools installed with the &os;
|
||||
base system
|
||||
without depending on other ports or databases.
|
||||
To install this utility
|
||||
as a port:</para>
|
||||
|
|
@ -1325,15 +1346,15 @@ The deinstallation will free 229 kB
|
|||
|
||||
<screen>&prompt.root; <userinput>portsclean -C</userinput></screen>
|
||||
|
||||
<para>In addition, a lot of out-dated source distribution files
|
||||
will collect in <filename>/usr/ports/distfiles</filename> over
|
||||
time. If <application>Portupgrade</application> is installed,
|
||||
this command will delete all the distfiles that are no longer
|
||||
<para>In addition, outdated source distribution files
|
||||
accumulate in <filename>/usr/ports/distfiles</filename> over
|
||||
time. To use <application>Portupgrade</application> to
|
||||
delete all the distfiles that are no longer
|
||||
referenced by any ports:</para>
|
||||
|
||||
<screen>&prompt.root; <userinput>portsclean -D</userinput></screen>
|
||||
|
||||
<para>To use <application>Portupgrade</application> to remove
|
||||
<para><application>Portupgrade</application> can remove
|
||||
all distfiles not referenced by any port currently installed
|
||||
on the system:</para>
|
||||
|
||||
|
|
@ -1344,11 +1365,11 @@ The deinstallation will free 229 kB
|
|||
|
||||
<screen>&prompt.root; <userinput>portmaster --clean-distfiles</userinput></screen>
|
||||
|
||||
<para>By default, this command is interactive and will prompt
|
||||
<para>By default, this command is interactive and prompts
|
||||
the user to confirm if a distfile should be deleted.</para>
|
||||
|
||||
<para>In addition to these commands, the
|
||||
<package>ports-mgmt/pkg_cutleaves</package> package or port
|
||||
<para>In addition to these commands,
|
||||
<package>ports-mgmt/pkg_cutleaves</package>
|
||||
automates the task of removing installed ports that are no
|
||||
longer needed.</para>
|
||||
</sect2>
|
||||
|
|
@ -1393,9 +1414,9 @@ The deinstallation will free 229 kB
|
|||
other configuration values are adequate.</para>
|
||||
|
||||
<para>The number of processor cores detected is used to define how
|
||||
many builds should run in parallel. Supply enough virtual
|
||||
many builds will run in parallel. Supply enough virtual
|
||||
memory, either with <acronym>RAM</acronym> or swap space. If
|
||||
virtual memory runs out, compiling jails will stop and be torn
|
||||
virtual memory runs out, the compilation jails will stop and be torn
|
||||
down, resulting in weird error messages.</para>
|
||||
|
||||
<sect2 xml:id="poudriere-initialization">
|
||||
|
|
@ -1496,7 +1517,7 @@ ports-mgmt/pkg
|
|||
|
||||
<screen>&prompt.root; <userinput>poudriere bulk -j <replaceable>10amd64</replaceable> -p <replaceable>local</replaceable> -z <replaceable>workstation</replaceable> -f <replaceable>10amd64-local-workstation-pkglist</replaceable></userinput></screen>
|
||||
|
||||
<para><keycombo
|
||||
<para>While running, pressing <keycombo
|
||||
action="simul"><keycap>Ctrl</keycap><keycap>t</keycap></keycombo>
|
||||
displays the current state of the build.
|
||||
<application>Poudriere</application> also builds files in
|
||||
|
|
@ -1504,7 +1525,7 @@ ports-mgmt/pkg
|
|||
that can be used with a web server to display build
|
||||
information.</para>
|
||||
|
||||
<para>Packages are now available for
|
||||
<para>After completion, the new packages are now available for
|
||||
installation from the <application>poudriere</application>
|
||||
repository.</para>
|
||||
|
||||
|
|
@ -1530,11 +1551,11 @@ ports-mgmt/pkg
|
|||
}</screen>
|
||||
|
||||
<para>Usually it is easiest to serve a poudriere repository to
|
||||
the client machines via HTTP. Setup a webserver to serve up
|
||||
the package directory, usually something like:
|
||||
<filename>/usr/local/poudriere/data/packages/<replaceable>10amd64</replaceable></filename>.
|
||||
Where <filename>10amd64</filename> is the name of the
|
||||
build.</para>
|
||||
the client machines via HTTP. Set up a webserver to serve up
|
||||
the package directory, for instance:
|
||||
<filename>/usr/local/poudriere/data/packages/<replaceable>10amd64</replaceable></filename>,
|
||||
where <filename><replaceable>10amd64</replaceable></filename>
|
||||
is the name of the build.</para>
|
||||
|
||||
<para>If the URL to the package repository is:
|
||||
<literal>http://pkg.example.com/10amd64</literal>, then the
|
||||
|
|
@ -1562,7 +1583,7 @@ ports-mgmt/pkg
|
|||
<listitem>
|
||||
<para>Most applications install at least one default
|
||||
configuration file in <filename>/usr/local/etc</filename>.
|
||||
In the case where an application has a large number of
|
||||
In cases where an application has a large number of
|
||||
configuration files, a subdirectory will be created to hold
|
||||
them. Often, sample configuration files are installed which
|
||||
end with a suffix such as <filename>.sample</filename>. The
|
||||
|
|
@ -1586,6 +1607,14 @@ ports-mgmt/pkg
|
|||
script in <filename>/usr/local/etc/rc.d</filename>. See
|
||||
<link linkend="configtuning-starting-services">Starting
|
||||
Services</link> for more information.</para>
|
||||
|
||||
<note>
|
||||
<para>By design, applications do not run their startup
|
||||
script upon installation, nor do they run their stop
|
||||
script upon deinstallation or upgrade. This decision
|
||||
is left to the individual system administrator.</para>
|
||||
</note>
|
||||
|
||||
</listitem>
|
||||
|
||||
<listitem>
|
||||
|
|
@ -1628,14 +1657,14 @@ ports-mgmt/pkg
|
|||
|
||||
<note>
|
||||
<para>Some ports are not maintained by an individual but
|
||||
instead by a <link
|
||||
instead by a group maintainer represented by a <link
|
||||
xlink:href="&url.articles.mailing-list-faq;/article.html">mailing
|
||||
list</link>. Many, but not all, of these addresses look
|
||||
like <email
|
||||
role="nolink">freebsd-listname@FreeBSD.org</email>.
|
||||
Take this into account when sending an email.</para>
|
||||
role="nolink">freebsd-<replaceable>listname</replaceable>@FreeBSD.org</email>.
|
||||
Please take this into account when sending an email.</para>
|
||||
|
||||
<para>In particular, ports shown as maintained by
|
||||
<para>In particular, ports maintained by
|
||||
<email role="nolink">ports@FreeBSD.org</email> are not
|
||||
maintained by a specific individual. Instead, any fixes
|
||||
and support come from the general community who subscribe
|
||||
|
|
|
|||
Loading…
Reference in a new issue