pkgsrc doc merge part 2
authormatthias <matthias@web>
Fri, 22 Oct 2010 10:19:22 +0000 (03:19 -0700)
committerCharlie <root@leaf.dragonflybsd.org>
Fri, 22 Oct 2010 10:19:22 +0000 (03:19 -0700)
docs/howtos/HowToPkgsrc.mdwn

index f110cfb..9824f2a 100644 (file)
@@ -1,5 +1,6 @@
 [[!toc levels=2 ]]
 
+The following page describes the basics of the pkgsrc system as used by DragonFly.
 
 ## pkgsrc Overview 
 
@@ -102,13 +103,15 @@ After switching to a new branch, it can be downloaded with:
     git checkout vendor
     git pull
 
-## Finding Your Application 
+## Dealing with pkgsrc packages
 
-Before you can install any applications you need to know what you want, and what the application is called. DragonFly's list of available applications is growing all the time. Fortunately, there are a number of ways to find what you want:
+The following section explains how to find, install and remove pkgsrc packages.
+
+### Finding Your Application 
 
-Since DragonFly 1.11 [pkg_search(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_search&section1) is included in the base system.  [pkg_search(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_search&section=1) searches an already installed pkgsrc® INDEX for for a given package name.  If pkgsrc is not installed or the INDEX file is missing, it fetches the [pkg_summary(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_summary&section=5) file.
+Before you can install any applications you need to know what you want, and what the application is called. DragonFly's list of available applications is growing all the time. Fortunately, there are a number of ways to find what you want:
 
- **Example. Find a Package** 
+Since DragonFly 1.11 [pkg_search(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_search&section1) is included in the base system.  [pkg_search(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_search&section=1) searches an already installed pkgsrc INDEX for for a given package name.  If pkgsrc is not installed or the INDEX file is missing, it fetches the [pkg_summary(5)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_summary&section=5) file.
 
     # pkg_search fvwm
     fvwm-2.4.20nb1          Newer version of X11 Virtual window manager
@@ -129,13 +132,13 @@ Its also possible to issue the command
     # cd /usr/pkgsrc/
     # bmake search key='package you are looking for'
 
-from the /usr/pkgsrc directory.
+from the `/usr/pkgsrc` directory.
 
-It's also possible to browse website that show all the available pkgsrc packages, such as [http://pkgsrc.se/](http://pkgsrc.se)
+It's also possible to browse website that show all the available pkgsrc packages, such as [http://pkgsrc.se/](http://pkgsrc.se) .
 
-## Installing packages from source
+### Installing packages from source
 
-Packages are built by going into the appropriate directory and issuing 'bmake install clean'. For example, to build the screen package you need to issue the following commands.
+Packages are built by going into the appropriate directory and issuing `bmake install clean`. For example, to build the *screen* package you need to issue the following commands.
 
     # cd /usr/pkgsrc/misc/screen
     # bmake install clean
@@ -150,21 +153,21 @@ To change options:
 
 Listing an option enables it.  Listing an option with a "-" before it disables the option.
 
-To make these option changes permanent for every future build or upgrade of this package, put a similar line in /usr/pkg/etc/mk.conf:
+To make these option changes permanent for every future build or upgrade of this package, put a similar line in `/usr/pkg/etc/mk.conf`:
 
      . PKG_OPTIONS.<package_name>=-option1 option2
     
-## Installing pre-built packages 
+### Installing pre-built packages 
 
-Binary packages can be installed using pkg_radd:
+Binary packages can be installed using *pkg_radd*:
 
     # pkg_radd screen
 
-This program works by setting the PKG_PATH enviroment variable to the appropriate path for the operating system and architecture to a remote repository of binary packages, and then using pkg_add to get packages.
+This program works by setting the `PKG_PATH` enviroment variable to the appropriate path for the operating system and architecture to a remote repository of binary packages, and then using pkg_add to get packages.
 
 You can manually set PKG_PATH and use pkg_add to get the same effect, using a different server.
 
-    # setenv PKG_PATH http://avalon.dragonflybsd.org/packages/i386/DragonFly-2.7/stable
+    # setenv PKG_PATH http://mirror-master.dragonflybsd.org/packages/i386/DragonFly-2.7/stable
     # pkg_add screen
 
 *Note:* The above URL is for the DragonFly-2.7 on i386.  Adjust the file path to match your installation and what's available on the server.
@@ -173,18 +176,18 @@ This will install most packages, but will not upgrade packages that are already
 
 ***Note:*** that the default remote repository for binary packages tracks quarterly pkgsrc releases, so your local install of pkgsrc should be the same quarterly release.
 
-Some packages are not licensed for distribution in binary form, so they may be able to build on DragonFly but won't be available with pkg_radd.  If pkg_radd fails, try going to that package's directory in /usr/pkgsrc and using 'bmake install clean'.
+Some packages are not licensed for distribution in binary form, so they may be able to build on DragonFly but won't be available with *pkg_radd*.  If it fails, try going to that package's directory and install the package manually as described above.
 
-### Dealing with different package versions 
+#### Dealing with different package versions 
 
-Due to the fact that the official packages are only build for the RELEASE-Version of DragonFly, it is possible that you see a warning when installing binary packages on a DEVELOPMENT-version of DragonFly.  The warning could look like this:
+It is possible that you see a warning when installing binary packages on a DEVELOPMENT-version of DragonFly.  The warning could look like this:
 
     pkg_add: Warning: package `vim-gtk2-7.1.116.tgz' was built for a different version of the OS:
     pkg_add: DragonFly/i386 1.10.1 (pkg) vs. DragonFly/i386 1.11.0 (this host)
 
 You can safely ignore this warning.  Normally all packages build for RELEASE run fine on DEVELOPMENT unless a major API-breakage was introduced.  In this case you would see a message from the developers on the appropriate mailing list.
 
-## List all installed packages 
+### List all installed packages 
 
 To obtain a list of all the packages that are installed on your system:
 
@@ -194,7 +197,7 @@ To see if certain packages have been installed, filter for the name of the packa
 
     # pkg_info | grep xorg
 
-## Removing packages
+### Removing packages
 
 If a program was installed as a package:
 
@@ -204,7 +207,7 @@ If a package was installed from the source files, you can also change to the dir
 
     # bmake deinstall
 
-### Remove associated files needed for building a package 
+#### Remove associated files needed for building a package 
 
 To remove the work file from building a package, and the package's dependencies:
 
@@ -227,16 +230,16 @@ There's a number of ways to upgrade pkgsrc; some of these are built in and some
 
 ### pkgin
 
-Downloads and installs binary packages.  Check the [[mirrors]] page for sites carrying binary packages to use with pkgin. You can run the following commands to get the packages updated.
+Downloads and installs binary packages.  Check the [[mirrors]] page for sites carrying binary packages to use with pkgin. You can run the following commands to get the packages updated. This assumes that *pkgin* is already configured. Please consult the documentation and the man page on how to do so.
 
     # pkgin update
     # pkgin full-upgrade 
 
 ### pkg_chk
 
-It updates packages by removing them and rebuilding them.  Warning: programs are unavailable until a rebuild finishes.  If they don't rebuild, it won't work. pkg_chk requires a few steps in order to work correctly. They are listed here.
+It updates packages by removing them and rebuilding them.  Warning: programs are unavailable until a rebuild finishes.  If they don't rebuild, it won't work. *pkg_chk* requires a few steps in order to work correctly. They are listed here.
 
-    # pkg_chk -g # make initial list of installed packages
+    # pkg_chk -g  # make initial list of installed packages
     # pkg_chk -r  # remove all packages that are not up to date and packages that depend on them
     # pkg_chk -a  # install all missing packages (use binary packages, this is the default)
     # pkg_chk -as # install all missing packages (build from source)
@@ -245,7 +248,7 @@ The above process removes all packages at once and installs the missing packages
 
 ### bmake update
 
-Performed in the /usr/pkgsrc directory that correlates with the installed package, the software is deleted and rebuilt.  The same warning applies as with pkg_chk.
+Performed in the `/usr/pkgsrc` directory that correlates with the installed package, the software is deleted and rebuilt.  The same warning applies as with *pkg_chk*.
 
 ### pkg_add -u
 
@@ -253,7 +256,7 @@ Point at a local or online binary archive location to download and update packag
 
 #### Update pkgsrc system packages
 
-**Note**: Sometimes, basic pkgsrc tools, like bmake or pkg_install, need to be upgraded.  However, they can't be deleted and replaced since you need that tool to accomplish replacement.  The solution is to build a separate package before deletion, and install that package. Inside the packages directory (/usr/pkgsrc/devel/bmake in this case)
+**Note**: Sometimes, basic pkgsrc tools, like bmake or pkg_install, need to be upgraded.  However, they can't be deleted and replaced since you need that tool to accomplish replacement.  The solution is to build a separate package before deletion, and install that package. Inside the packages directory (`/usr/pkgsrc/devel/bmake` in this case)
 
     # env USE_DESTDIR=full bmake package
     # bmake clean-depends clean
@@ -262,22 +265,57 @@ And go to the packages directory and install the binary package with
 
     # pkg_add -u <pkg_name> (i.e. the name of the .tgz file).
     # bmake replace USE_DESTDIR=yes
-## Additional /usr/pkg/etc/mk.conf notes
 
-Packages often install rc.d scripts to control software running on startup.  To specify where the rc.d scripts from the installed packages should go:
+## Start pkgsrc applications on system startup
+
+Packages often install rc.d scripts to control software running on startup.  To specify where the rc.d scripts from the installed packages should go, add the following lines to your `/usr/pkg/etc/mk.conf` file:
 
     RCD_SCRIPTS_DIR=/etc/rc.d
     PKG_RCD_SCRIPTS=YES
 
-This option can be set in the environment to activate it for binary packages.  These packages will still have to be enabled in rc.conf to run at boot.  If these options aren't set, the rc file will be placed in /usr/pkg/share/examples/rc.d/ and will need to be manually copied over to /etc/rc.d.
+This option can be set in the environment to activate it for binary packages.  These packages will still have to be enabled in `/etc/rc.conf/ to run at boot.  If these options aren't set, the rc file will be placed in `/usr/pkg/share/examples/rc.d/` and will need to be manually copied over to `/etc/rc.d`.
+
+Many other options can be set in this file; see `/usr/pkgsrc/mk/defaults/mk.conf` for examples.
+
+## Miscellaneous topics
+
+### Post-installation Activities 
+
+After installing a new application you will normally want to read any documentation it may have included, edit any configuration files that are required, ensure that the application starts at boot time (if it is a daemon), and so on.
+ The exact steps you need to take to configure each application will obviously be different. However, if you have just installed a new application and are wondering *What now?* These tips might help:
+
+Use [pkg_info(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=pkg_info&section=1) to find out which files were installed, and where. For example, if you have just installed Foo_Package version 1.0.0, then this command
+
+    # pkg_info -L foopackage-1.0.0 | less
+
+will show all the files installed by the package. Pay special attention to files in `man/` directories, which will be manual pages, `etc/` directories, which will be configuration files, and `doc/`, which will be more comprehensive documentation. If you are not sure which version of the application was just installed, a command like this
+
+    # pkg_info | grep -i foopackage
+
+will find all the installed packages that have <i>foopackage</i> in the package name. Replace <i>foopackage</i> in your command line as necessary.
+
+Once you have identified where the application's manual pages have been installed, review them using [man(1)](http://leaf.dragonflybsd.org/cgi/web-man?command=man&section=1). Similarly, look over the sample configuration files, and any additional documentation that may have been provided. If the application has a web site, check it for additional documentation, frequently asked questions, and so forth. If you are not sure of the web site address it may be listed in the output from
+
+    # pkg_info foopackage-1.0.0
+
+  
+A `WWW:` line, if present, should provide a URL for the application's web site.
+
+### Dealing with Broken Packages 
+
+If you come across a package that does not work for you, there are a few things you can do, including:
+
+  1. Fix it! The [pkgsrc Guide](http://www.netbsd.org/Documentation/pkgsrc/) includes detailed information on the ***pkgsrc®*** infrastructure so that you can fix the occasional broken package or even submit your own!
+
+  1. Send email to the maintainer of the package first. Type `bmake maintainer` or read the `Makefile` to find the maintainer's email address. Remember to include the name and version of the port (send the `$NetBSD:` line from the `Makefile`) and the output leading up to the error when you email the maintainer. If you do not get a response from the maintainer, you can try [users](http://leaf.dragonflybsd.org/mailarchive/) .
 
-Many other options can be set in this file; see /usr/pkgsrc/mk/defaults/mk.conf for examples.
+  1. Grab a pre-built package from an [[mirror|mirrors]] site near you. 
 
-## What is WIP? 
+### What is WIP? 
 
 Packages that can be built within the pkgsrc framework but are not yet necessarily ready for production use can be found in [http://pkgsrc-wip.sourceforge.net](http://pkgsrc-wip.sourceforge.net).  These packages need to be downloaded separately; check the website for details.  Packages in this collection are in development and may not build successfully.
 
-## Links
+### Links
 
 * [http://www.netbsd.org/Documentation/pkgsrc/](http://www.netbsd.org/Documentation/pkgsrc/)