(no commit message)
[ikiwiki.git] / docs / howtos / HowToPkgsrc.mdwn
1 [[!toc levels=2 ]]
2
3 ## History and Overview 
4 [Pkgsrc](http://www.pkgsrc.org) is a packaging system that was originally created for NetBSD. It has been ported to DragonFly, along with other operating systems.  Pkgsrc is very similar to FreeBSD's ports mechanism.
5
6 ## Installing pkgsrc 
7
8 The basic pkgsrc tools are provided with every DragonFly system as part of installation.  However, you still need to download the pkgsrc tree for building applications with these tools.  
9
10 As root:
11
12     # cd /usr
13     # make pkgsrc-create
14
15 to fetch the intial pkgsrc repository from the net, or
16
17     # cd /usr
18     # make pkgsrc-update
19
20 to update.
21
22 Edit /usr/Makefile to select a different download location, if desired.
23
24 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.
25
26 ## Installing packages from source
27
28 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.
29
30     # cd /usr/pkgsrc/misc/screen
31     # bmake install clean
32
33 To find out the options that can affect how a program is built:
34
35     # bmake show-options
36
37 To change options:
38
39     # bmake PKG_OPTIONS.<package_name>="-option1 option2" install clean
40
41 Listing an option enables it.  Listing an option with a "-" before it disables the option.
42
43 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:
44
45      . PKG_OPTIONS.<package_name>=-option1 option2
46     
47 ## Installing pre-built packages 
48
49 Binary packages can be installed using pkg_radd:
50
51     # pkg_radd screen
52
53 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.
54
55 You can manually set PKG_PATH and use pkg_add to get the same effect, using a different server.
56
57     # setenv PKG_PATH http://avalon.dragonflybsd.org/packages/i386/DragonFly-2.7/stable
58     # pkg_add screen
59
60 ( for i386 packages )
61
62 or
63
64     # setenv PKG_PATH http://avalon.dragonflybsd.org/packages/x86_64/DragonFly-2.6/stable/All/
65     # pkg_add screen
66
67 ( for x86_64 packages )
68
69 This will install most packages, but will not upgrade packages that are already installed.
70
71 ***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.***
72
73 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'.
74
75 ### Tracking the stable branch 
76
77 There are quarterly releases of pkgsrc that are specifically designed for stability.  You should in general follow the latest branch, rather than bleeding edge pkgsrc.
78
79 To see the available branches:
80
81     cd /usr/pkgsrc 
82     git branch -r
83
84 To switch to a recent branch:
85
86     cd /usr/pkgsrc 
87     git branch pkgsrc-2010Q3 origin/pkgsrc-2010Q3
88
89 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.
90
91 After switching to a new branch, it can be downloaded with:
92
93     cd /usr/pkgsrc 
94     git checkout vendor
95     git pull
96
97 ### List all installed packages 
98
99 To obtain a list of all the packages that are installed on your system:
100
101     # pkg_info
102
103 To see if certain packages have been installed, filter for the name of the package.  This example will show all xorg-related packages currently installed on the system:
104
105     # pkg_info | grep xorg
106
107 ### Searching available packages 
108
109 Packages can be found using one of two ways. You can issue the command
110
111     # cd /usr/pkgsrc/
112     # bmake search key='package you are looking for'
113
114 from the /usr/pkgsrc directory.
115
116 There is also the pkglocate tool that comes with pkgsrc:
117
118     # /usr/pkgsrc/pkglocate 'package name'
119
120 Normal UNIX file finding commands will work (whereis, locate, or find).
121
122 It's also possible to browse website that show all the available pkgsrc packages, such as [http://pkgsrc.se/](http://pkgsrc.se)
123
124 ## Upgrading packages 
125
126 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.
127
128 pkg_rolling-replace: Rebuilds packages from source in dependency order.
129
130 pkgin: Downloads and installs binary packages.  Check the [[mirrors]] page for sites carrying binary packages to use with pkgin. Just remember that our x86_64 branch used to be called amd64. The amd64 alias is preserved in order to support older installations.
131
132 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.
133
134 '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.
135
136 'pkg_add -u': point at a local or online binary archive location to download and update packages.
137
138
139
140 ## Removing packages
141
142 If a program was installed as a package:
143
144     # pkg_delete packagename
145
146 If a package was installed from the source files, you can also change to the directory they were installed from and issue the command:
147
148     # bmake deinstall
149
150 ### Remove associated files needed for building a package 
151
152 To remove the work file from building package
153
154     # bmake clean
155
156 This can be combined with other steps:
157
158     # bmake install clean 
159
160 ## Additional /usr/pkg/etc/mk.conf notes
161
162 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:
163
164     RCD_SCRIPTS_DIR=/etc/rc.d
165     PKG_RCD_SCRIPTS=YES
166
167 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.
168
169 ## What is WIP? 
170
171 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.
172
173 ## Links
174
175 * [http://www.netbsd.org/Documentation/pkgsrc/](http://www.netbsd.org/Documentation/pkgsrc/)
176
177 * [http://www.pkgsrc.se](http://www.pkgsrc.se)
178
179 * 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'.
180
181 * [http://pkgsrc-wip.sourceforge.net](http://pkgsrc-wip.sourceforge.net), **w**ork **i**n **p**rogress packages not yet in official pkgsrc release
182
183 * The #pkgsrc IRC channel on Freenode
184
185 * The #dragonflybsd IRC channel on EFnet