More work
authorjustin <justin@web>
Tue, 28 Sep 2010 02:42:04 +0000 (19:42 -0700)
committerCharlie <root@leaf.dragonflybsd.org>
Tue, 28 Sep 2010 02:42:04 +0000 (19:42 -0700)
docs/howtos/HowToPkgsrc.mdwn

index 672b92a..bb8c531 100644 (file)
@@ -21,7 +21,10 @@ to update.
 
 Edit /usr/Makefile to select a different download location, if desired.
 
+This downloads the absolute most recent version of pkgsrc.  In a production environment, you may want a more stable release.  Check the section below titled "Tracking the stable branch" for more details.
+
 ## 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.
 
     # cd /usr/pkgsrc/misc/screen
@@ -56,7 +59,7 @@ You can manually set PKG_PATH and use pkg_add to get the same effect, using a di
 
 This will install most packages, but will not upgrade packages that are already installed.
 
-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.
+***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'.
 
@@ -69,12 +72,12 @@ To see the available branches:
     cd /usr/pkgsrc 
     git branch -r
 
-To switch to the most recent branch:
+To switch to a recent branch:
 
     cd /usr/pkgsrc 
     git branch pkgsrc-2010Q3 origin/pkgsrc-2010Q3
 
-Branch naming format is 'pkgsrc-YYYYQX', where YYYY is the year and QX is quarters 1-4 of the year.
+Branch naming format is 'pkgsrc-YYYYQX', where YYYY is the year and QX is quarters 1-4 of the year.  Check [pkgsrc.org](http://www.pkgsrc.org/) to see the name of the most recently released branch.
 
 After switching to a new branch, it can be downloaded with:
 
@@ -111,119 +114,65 @@ It's also possible to browse website that show all the available pkgsrc packages
 
 ## Upgrading packages 
 
-Note: Up to date information about this can be found in this web page: http://wiki.netbsd.se/index.php/How_to_upgrade_packages
-
-pkgsrc comes with a list of utilities that make package management easier. These files are located in /usr/pkgsrc/pkgtools. One of the items in this directory is pkg_chk which is similar to FreeBSD's portupgrade. Some commands that are worth noting while using pkg_chk are:
-
-Make initial list of installed packages:
-
-    # pkg_chk -g
-
-Remove all packages that are not up to date and packages that depend on them:
-
-    # pkg_chk -r
-
-Install all missing packages (use binary packages, this is the default):
-
-    # pkg_chk -a
+There's a number of ways to upgrade pkgsrc; some of these are built in and some are packages installable with pkgsrc.  This list is not necessarily comprehensive.
 
-Install all missing packages (build from source):
+pkg_rolling-replace: Rebuilds packages from source in dependency order.
 
-    pkg_chk -as
+pkgin: Downloads and installs binary packages.  Check the [[mirrors]] page for sites carrying binary packages to use with pkgin.
 
-If you want to see a list of upgradeable packages, you can use the lintpkgsrc tool. Install the package pkgtools/lintpkgsrc and do a:
+pkg_chk: will update package by removing them and rebuilding them.  Warning: programs are unavailable until a rebuild finishes.  If they don't rebuild, it won't work.
 
-    lintpkgsrc -i
+'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.
 
-It will list the packages, which could be updated.
+'pkg_add -u': point at a local or online binary archive location to download and update packages.
 
 
-### Quick binary upgrades with pkgsrc 
-A disadvantage of using pkg_chk is that it deletes old packages before upgrading to newer versions of those packages.  If the upgrades need to be built from source, or downloaded, this makes the packaged software unavailable during the potentially long time of the upgrade.
-
-A solution is to download binary packages ahead of time and install from those local files, keeping downtime to a minimum.  The steps to accomplish that with pkg_chk are as follows:
-
-This step creates the pkg_chk.conf file, which lists the packages installed on your system.  This only needs to be run the first time this process is followed.
-
-    
-    pkg_chk -P ftp://binary/url -abg 
-
-This command downloads all the binary packages needed to upgrade pkgsrc.
-
-    
-    pkg_chk -P ftp://binary/url -abf  
-
-This final step removes old packages and installs the already-downloaded up-to-date versions.  It is during this step that pkgsrc packages are unavailable.
-
-    
-    pkg_chk -P /wherever/previous/step/put/binaries -abu 
 
+## Removing packages
 
-Note that ftp://binary/url represents the URL to an online binary pkgsrc repository, such as in the PKG_PATH example on this page.
+If a program was installed as a package:
 
-If the first command returns an error, try creating a blank file called 'Makefile' in the directory where these commands are run.  'touch Makefile' will create this empty file.
+    # pkg_delete packagename
 
-## Removing packages
-The command pkg_delete will remove any package that has been previously installed on a system. If a package was installed from the source files, you can also change to the directory they were installed from and issue the command:
+If a package was installed from the source files, you can also change to the directory they were installed from and issue the command:
 
     # bmake deinstall
 
 ### Remove associated files needed for building a package 
-To remove the temporary source/object files that are associated with a package, you can issue the bmake clean command. This can also be performed on the same stage as the installation by using the following make command bmake install clean. The latter is more commonly done for simplicity reasons.
-
-## Additional mk.conf notes
-
-The default location of mk.conf is /usr/pkg/etc
-To specify where the rc.d scripts from the installed packages should go:
-
-    RCD_SCRIPTS_DIR=/etc/rc.d
 
-To enable the automatic installation of rc.d scripts into the $RCD_SCRIPTS_DIR directory:
+To remove the work file from building package
 
-    PKG_RCD_SCRIPTS=YES
-
-This option can be set in the environment to activate it for binary packages.
-
-If you have already partially downloaded a file, this option makes it resume the transfer:
-
-    PKG_RESUME_TRANSFERS=YES
+    # bmake clean
 
-If the checksum is not correct, automatically download from the next download site:
+This can be combined with other steps:
 
-    FAILOVER_FETCH=YES
+    # bmake install clean 
 
-To enable suffixing work directories with the machine's hostname (needed for PKGSRC_LOCKTYPE):
+## Additional /usr/pkg/etc/mk.conf notes
 
-    OBJHOSTNAME=
+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:
 
-To enable locking (so that only one process is working on the same package at the same time - sleep means that it should sleep for 5 seconds and try again (5 seconds is by default)):
-    PKGSRC_LOCKTYPE=sleep
-
-To enable sending of MESSAGE file upon installation of a package to a specific user:
-
-    PKGSRC_MESSAGE_RECIPIENTS=username
+    RCD_SCRIPTS_DIR=/etc/rc.d
+    PKG_RCD_SCRIPTS=YES
 
-To clean easly the dependencies after compiling:
+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.
 
-    CLEANDEPENDS=YES
+## What is WIP? 
 
-## Where is my http://pkgsrc.se/wip dir? 
-[[http://pkgsrc.se/wip]] shows some interessting ports, especially if you are into java, but you will not find them in your default pkgsrc dir. Take a look at [[http://pkgsrc-wip.sourceforge.net]], there is a description how to get and update.
+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](pkgsrc-wip).  These packages need to be downloaded separately; check the website for details.  Packages in this collection are in development and may not build successfully.
 
-## Where to go for more help 
+## Links
 
-* The NetBSD pkgsrc developers have a lot of pkgsrc documentation on this website (http://www.netbsd.org/Documentation/pkgsrc/).
+* [http://www.netbsd.org/Documentation/pkgsrc/](http://www.netbsd.org/Documentation/pkgsrc/)
 
-* To find packages or updates, look at http://www.pkgsrc.se.
+* [http://www.pkgsrc.se](http://www.pkgsrc.se)
 
-* To query and/or report bugs against packages in pkgsrc, look at http://www.netbsd.org/support/send-pr.html category 'pkg'.
+* To search and/or report bugs against packages in pkgsrc, look at [http://www.netbsd.org/support/send-pr.html](http://www.netbsd.org/support/send-pr.html) - use category 'pkg'.
 
-* To get and update wip, look at http://pkgsrc-wip.sourceforge.net.
+* [http://pkgsrc-wip.sourceforge.net](pkgsrc-wip), **w**ork **i**n **p**rogress packages not yet in offical pkgsrc release
 
-* The pkgsrc IRC channel on Freenode (http://www.freenode.net) (#pkgsrc) is another resource for pkgsrc users and devleopers.
+* The #pkgsrc IRC channel on Freenode
 
-* The DragonFlyBSD IRC channel on EFnet (http://www.efnet.org) (#dragonflybsd) is frequented by DragonFly users and developers using pkgsrc.
+* The #dragonflybsd IRC channel on EFnet
 
-There's also a RSS feed "NetBSD - Fresh Packages" available: http://www.netbsd.org/Changes/rss-netbsd-pkgs.xml
+* [http://www.netbsd.org/Changes/rss-netbsd-pkgs.xml](New and updated pkgsrc packages via RSS)