Added dfly config walkthrough, removed deprecated walkthrough
[ikiwiki.git] / docs / howtos / HowToDPorts / index.mdwn
index 5007103..1182671 100644 (file)
 
 Dports is DragonFly's own third-party software build system.  It is based on FreeBSD's Ports Collection.  Differences between ports and DPorts are intentionally kept to a minimum, both to maintain familiarity for mutual users of both operating systems and also to leverage the tremendous amount of work the FreeBSD contributors put into ports.  DPorts can and does feature ports unique to DragonFly, so it's truly a native system.
 
-The __pkgng__ tool called "pkg" is a modern and fast binary package manager.  It was developed for FreeBSD, but PC-BSD used in production first, followed soon after by DragonFly.  In the future, it will be only binary package manager on FreeBSD just as it is for DPorts.
+The __pkgng__ tool called "pkg" is a modern and fast binary package manager.  It was developed for FreeBSD, but PC-BSD used it in production first, followed soon after by DragonFly.  In the future, it will be the only binary package manager on FreeBSD, just it is the only port manager in DPorts.
 
-__pkgng__ is not a replacement for port management tools like `ports-mgmt/portmaster` or `ports-mgmt/portupgrade`. While `ports-mgmt/portmaster` and `ports-mgmt/portupgrade` can install third-party software from both binary packages and DPorts, __pkgng__ installs only binary packages.
+__pkgng__ is not a replacement for port management tools like `ports-mgmt/portmaster` or `ports-mgmt/portupgrade`. While `ports-mgmt/portmaster` and `ports-mgmt/portupgrade` can install third-party software from both binary packages and DPorts, __pkgng__ installs only binary packages.  On the other hand, many people use __pkgng__ by itself and never install the optional portupgrade or portmaster tools.
 
 ## Getting started with pkgng
 
-DragonFly daily snapshots and Releases (starting with 3.4) come with __pkgng__ already installed.  However upgrades from earlier releases won't have it.  If the "pkg" program is missing on the system for any reason, it can be quickly bootstrapped without having to build it from source.
+DragonFly daily snapshots and Releases (starting with 3.4) come with __pkgng__ already installed.  Upgrades from earlier releases, however, will not have it.  If the "pkg" program is missing on the system for any reason, it can be quickly bootstrapped without having to build it from source or even having dports installed:
 
-To bootstrap __pkgng___ on the system, run:
-
-    # cd /usr
     # make pkg-bootstrap
     # rehash
     # pkg-static install -y pkg
     # rehash
 
-If the DPorts source tree is already present on the system, pkg can quickly be built from source:
+If pkgsrc has ever been installed on the system, make sure all binaries produced by it have been removed:
 
-    # cd /usr/dports/ports-mgmt/pkg
-    # make install
+    # rm -rf /usr/pkg
+
+Currently it's necessary to manually install the configuration file, but this requirement should disappear in the future.  After installing the configuration file, you may want to open it up and edit it to select a different mirror.
 
-## Configuring the pkgng Environment
+## Configuring pkgng
 
-The __pkgng__ package management system uses a package repository for most operations. The default package repository location is defined in `/usr/local/etc/pkg.conf` or the `PACKAGESITE` environment variable, which overrides the configuration file.  Additional __pkgng__ configuration options are described in pkg.conf(5).
+Older versions of pkgng saved their configuration at /usr/local/etc/pkg.conf; this file made reference to a PACKAGESITE.  pkgng will still work based on this file, but will output errors:
 
-The pkg.conf file comes preinstalled with the latest release repository pre-selected.
+    # pkg update
+    pkg: PACKAGESITE in pkg.conf is deprecated. Please create a repository configuration file
+    Updating repository catalogue
+    pkg: Warning: use of http:// URL scheme with SRV records is deprecated: switch to pkg+http://
+
+If you do __not__ see these errors, then skip to "Now, navigate to `/usr/local/etc/pkg/repos/`", otherwise:
 
-    PACKAGESITE: http://avalon.dragonflybsd.org/dports/${ABI}/RELEASE
+Listen to the errors: hash out the packagesite line, save the file, and move on.  This can be done with vi:
 
-The RELEASE repository is static, but the LATEST repository is periodically updated.  If bleeding edge is wanted, change pkg.conf to reflect that:
+    # vi /usr/local/etc/pkg.conf
 
-    PACKAGESITE: http://avalon.dragonflybsd.org/dports/${ABI}/LATEST
+There will be two lines in the file like this:
 
-DragonFly users on the development branch can also use pre-built binary packages from the last release, but they will need to override the ABI in pkg.conf, e.g.:
+    # Default Dports package server (California)
+    PACKAGESITE: http://mirror-master.dragonflybsd.org/dports/${ABI}/LATEST
 
-    ABI: dragonfly:3.4:x86:32  # for i386 platform
-    ABI: dragonfly:3.4:x86:64  # for x86-64 platform
+Hash out the offending line:
 
-There are already a few mirrors available which can be set in pkg.conf
+    # Default Dports package server (California)
+    # PACKAGESITE: http://mirror-master.dragonflybsd.org/dports/${ABI}/LATEST
 
-* North America: http://avalon.dragonflybsd.org/dports/${ABI}/LATEST
-* Europe: http://pkg.wolfpond.org/${ABI}/LATEST
-* Europe: http://mirrors.ircam.fr/pub/DragonFlyBSD-dports/${ABI}/LATEST
-* Europe: http://dfly.schlundtech.de/dports/${ABI}/LATEST
+Note that, as of time of writing, there are two working package repositories:
 
-IPV6 users are welcome to use dfly.schlundtech.de
+    # Default Dports package server (California)
+    # PACKAGESITE: http://mirror-master.dragonflybsd.org/dports/${ABI}/LATEST
+    
+    # European mirrors
+    [...]
+    #PACKAGESITE: http://dfly.schlundtech.de/dports/${ABI}/LATEST
+
+Test their performance---we will be using the fastest one.  This may, or may not, be the one closest to you (the California site for the New World, the German site for the Old World).
+
+    # ping schlundtech.de
+    PING schlundtech.de (85.236.36.90): 56 data bytes
+    64 bytes from 85.236.36.90: icmp_seq=0 ttl=49 time=101.433 ms
+    64 bytes from 85.236.36.90: icmp_seq=1 ttl=49 time=59.177 ms
+    64 bytes from 85.236.36.90: icmp_seq=2 ttl=49 time=79.550 ms
+    64 bytes from 85.236.36.90: icmp_seq=3 ttl=49 time=88.268 ms
+    64 bytes from 85.236.36.90: icmp_seq=4 ttl=49 time=120.060 ms
+    [...]
+    --- schlundtech.de ping statistics ---
+    20 packets transmitted, 19 packets received, 5.0% packet loss
+    round-trip min/avg/max/stddev = 49.555/96.064/186.662/33.559 ms
+    # ping mirror-master.dragonflybsd.org
+    PING avalon.dragonflybsd.org (199.233.90.72): 56 data bytes
+    64 bytes from 199.233.90.72: icmp_seq=0 ttl=47 time=208.013 ms
+    64 bytes from 199.233.90.72: icmp_seq=1 ttl=47 time=256.441 ms
+    64 bytes from 199.233.90.72: icmp_seq=2 ttl=47 time=281.436 ms
+    64 bytes from 199.233.90.72: icmp_seq=3 ttl=47 time=281.103 ms
+    64 bytes from 199.233.90.72: icmp_seq=4 ttl=47 time=285.440 ms
+    [...]
+    --- avalon.dragonflybsd.org ping statistics ---
+    19 packets transmitted, 19 packets received, 0.0% packet loss
+    round-trip min/avg/max/stddev = 208.013/264.017/334.180/31.549 ms
+
+Now, navigate to `/usr/local/etc/pkg/repos/` and rename one of the configuration file samples you find there. `df-latest.conf` will make pkg use the newest available binaries while `df-release.conf` points to binaries built at the time of the release. The latter is frozen so you will not get any updates. Edit the one you renamed:
+
+    # cd /usr/local/etc/pkg/repos/
+    # ls
+    df-latest.conf.sample      df-releases.conf.sample
+    # cp -v df-latest.conf.sample df-latest.conf
+    df-latest.conf.sample -> df-latest.conf
+    # chmod -v 644 df-latest.conf
+    df-latest.conf
+    # vi df-latest.conf
+
+Enable whichever server was faster (Avalon is American, SchlundTech is German), and pkg+ to the url and SRV to mirror_type:
+
+    Avalon: {
+        url             : pkg+http://mirror-master.dragonflybsd.org/dports/${ABI}/LATEST,
+        mirror_type     : SRV
+        [...]
+        enabled         : no
+    }
+    SchlundTech: {
+        url             : pkg+http://dfly.schlundtech.de/dports/${ABI}/LATEST,
+        mirror_type     : SRV
+        [...]
+        enabled         : yes
+    }
+
+Before using, consult the man page (`man pkg`) and then try these examples:
+
+    # pkg search editors
+    # pkg install vim
 
 ## Basic pkgng Operations
 
@@ -92,7 +154,7 @@ For example, to install curl:
     
     Proceed with installing packages [y/N]: y
     ca_root_nss-3.13.5.txz           100%    255KB   255.1KB/s  255.1KB/s   00:00
-    curl-7.24.0.txz                  100%    1108KB  1.1MB/s    1.1MB/s     00:00
+    curl-7.24.0.txz                  100%   1108KB     1.1MB/s    1.1MB/s   00:00
     Checking integrity... done
     Installing ca_root_nss-3.13.5... done
     Installing curl-7.24.0... done
@@ -163,7 +225,7 @@ __pkgng__ includes its own package database backup mechanism. To manually back u
 
     # pkg backup -d <pkgng.db>
 
-Additionally, __pkgng__ includes a periodic(8) script to automatically back up the package database daily if `daily_backup__pkgng__enable` is set to `YES` in periodic.conf(5).   To prevent the `pkg_install` periodic script from also backing up the package database, set `daily_backup_pkgdb_enable` to `NO` in periodic.conf(5).
+Additionally, __pkgng__ includes a periodic(8) script to automatically back up the package database daily if `daily_backup_pkgng_enable` is set to `YES` in periodic.conf(5).   To prevent the `pkg_install` periodic script from also backing up the package database, set `daily_backup_pkgdb_enable` to `NO` in periodic.conf(5).
 
 To restore the contents of a previous package database backup, run:
 
@@ -239,3 +301,7 @@ Building from source works similar to ports and pkgsrc: cd into the appropriate
 To take all the default build options and avoid getting the pop-up dialog box, set `NO_DIALOG=yes` on either the command line or the make.conf file.
 
 If you just want to set the options for one package, and accept the default for all of its dependencies, do 'make config' in the package in you want non-default options, and then 'make NO_DIALOG=yes'.  Note that this is only necessary if you want to build from source with a non-default set of options, or if no pre-built binary package is available yet.
+
+## More reading
+* How fix/add broken ports: [[docs/howtos/fixdports]]
+* [Trick: How to get i386-only software via dports](http://leaf.dragonflybsd.org/mailarchive/users/2013-06/msg00023.html)