Annotation of wikisrc/pkgsrc/intro_to_packaging.mdwn, revision 1.10
1.2 schmonz 1: This guide should allow you to learn how to create a new port or
2: simply fix a port that you need. There are three target demographics
3: listed below:
1.1 schmonz 4:
1.2 schmonz 5: - binary packages user with pkgin or pkg_add
1.1 schmonz 6: (you should be confident here)
1.2 schmonz 7: - build from source, use options
1.1 schmonz 8: (you will know this after reading the guide)
9: - port developers
10: (you should be able to get started here)
11:
12:
13: ## pkgsrc tree
14:
1.2 schmonz 15: You should have a copy of the pkgsrc tree sitting somewhere on your
1.6 wiki 16: disk, already bootstrapped.
1.2 schmonz 17: The tree contains a `Makefile`, a `README`, distfiles, packages,
18: category directories containing the ports, the bootstrap directory
19: and some documentation.
1.1 schmonz 20:
1.2 schmonz 21: The `mk/*` directory contains the pkgsrc framework Makefiles but
22: also shell and Awk scripts
1.1 schmonz 23:
1.2 schmonz 24: `pkglocate` is a script to find port names in the tree, though
25: `pkgtools/pkgfind` is much faster.
1.1 schmonz 26:
27:
28: ## use the right tools
29:
1.2 schmonz 30: If you want to get started working on ports like creating new ones
31: or simply fix ones you need, you should know about these tools:
1.1 schmonz 32:
1.2 schmonz 33: - install package developer utilities:
1.1 schmonz 34:
35: pkgin -y in pkg_developer
36:
37: It contains very useful programs like:
38:
1.2 schmonz 39: - checkperms:
1.1 schmonz 40:
41: verify file permissions
42: - createbuildlink:
1.2 schmonz 43:
1.1 schmonz 44: create buildlink3.mk files, which I'll explain later
45: - digest:
1.2 schmonz 46:
1.1 schmonz 47: create hashes for messages with crypto algorithms such as sha512 and many others
48: - lintpkgsrc:
49:
50: checks the whole pkgsrc tree, list all explicitly broken packages for example
51: - pkg_chk:
52:
53: checks package versions and update if necessary
54: - pkg_tarup:
55:
56: create archives of installed programs for later use on other machines or backups
57: - pkgdiff:
1.2 schmonz 58:
59: show diffs of patched files
1.1 schmonz 60: - pkglint:
61:
62: verify the port you're creating for common mistakes (very useful!)
63: - revbump:
64:
65: update package version by one bump by increasing PKGREVISION
66: - url2pkg:
67:
68: create a blank port from the software download link, it saves you some time by filling out a few basic Makefile settings
69: - verifypc:
70:
71: sanity check for pkg-config in ports
72:
73:
74: ## port contents
75:
76: A pkgsrc port should at least contain:
77:
1.2 schmonz 78: - `Makefile` : a comment, developer info, software download site
79: and lots of other possibilities
80: - `DESCR` : a paragraph containing the description for the software
81: of the port we're making
82: - `PLIST` : the list of files to install, pkgsrc will only install
83: the files listed here to your prefix
84: - `distinfo` : hashes of the software archive and patches or files
85: in the port
1.1 schmonz 86:
87:
1.2 schmonz 88: Here's how they would look like for a small port I submitted not
89: long ago in pkgsrc-wip
1.1 schmonz 90:
1.2 schmonz 91: Makefile:
1.1 schmonz 92:
1.10 ! schmonz 93: [[!format makefile """
1.3 schmonz 94: # [[!paste id=rcsid1]][[!paste id=rcsid2]]
1.1 schmonz 95:
96: PKGNAME= osxinfo-0.1
97: CATEGORIES= misc
98: GHCOMMIT= de74b8960f27844f7b264697d124411f81a1eab6
99: DISTNAME= ${GHCOMMIT}
100: MASTER_SITES= https://github.com/yrmt/osxinfo/archive/
101:
102: MAINTAINER= youri.mout@gmail.com
103: HOMEPAGE= http://github.com/yrmt/osxinfo
104: COMMENT= Small Mac OS X Info Program
105: LICENSE= isc
106:
107: ONLY_FOR_PLATFORM= Darwin-*-*
108:
109: DIST_SUBDIR= osxinfo
110: WRKSRC= ${WRKDIR}/osxinfo-${GHCOMMIT}
111:
112: .include "../../databases/sqlite3/buildlink3.mk"
113: .include "../../mk/bsd.pkg.mk"
1.4 schmonz 114: """]]
1.1 schmonz 115:
1.2 schmonz 116: DESCR:
1.1 schmonz 117:
1.7 wiki 118: Small and fast Mac OS X info program written in C.
1.1 schmonz 119:
120:
121: PLIST:
122:
1.3 schmonz 123: @comment [[!paste id=rcsid1]][[!paste id=rcsid2]]
1.1 schmonz 124: bin/osxinfo
125:
126: distinfo:
127:
1.3 schmonz 128: [[!paste id=rcsid1]][[!paste id=rcsid2]]
1.1 schmonz 129:
130: SHA1 (osxinfo/de74b8960f27844f7b264697d124411f81a1eab6.tar.gz) = 83a2838ad95ff73255bea7f496a8cc9aaa4e17ca
131: RMD160 (osxinfo/de74b8960f27844f7b264697d124411f81a1eab6.tar.gz) = 9102eb2a938be38c4adf8cfbf781c04d0844d09a
132: Size (osxinfo/de74b8960f27844f7b264697d124411f81a1eab6.tar.gz) = 5981 bytes
133:
134:
135: ## make
136:
1.2 schmonz 137: Now you know what kind of files you can see when you're in a port
138: directory. The command used to compile it is the NetBSD `make` but
139: often `bmake` on non NetBSD systems to avoid Makefile errors. Typing
140: make alone will only compile the program but you can also use other
141: command line arguments to make such as extract, patch, configure,
142: install, package, ...
1.1 schmonz 143:
144: I'll try to list them and explain them in logical order. You can run them together.
145:
1.2 schmonz 146: - `make clean` will remove the source file from the work directory
147: so you can restart with either new options, new patches, ...
148: - `make fetch` will simply fetch the file and check if the hash
149: corresponds. It will throw an error if it doesn't.
150: - `make distinfo` or `make mdi` to update the file hashes in the
151: `distinfo` file mentionned above.
152: - `make extract` extracts the program source files from it's archive
153: in the work directory
1.1 schmonz 154: - `make patch` applies the local pkgsrc patches to the source
155: - `make configure` run the GNU configure script
1.2 schmonz 156: - `make` or `make build` or `make all` will stop after the program
157: is compiled
158: - `make stage-install` will install in the port destdir, where
159: pkgsrc first installs program files to check if the files correspond
160: with the `PLIST` contents before installing to your prefix. For
161: `wget`, if you have a default WRKOBJDIR (I'll explain later), the
162: program files will first be installed in
163: `<path>/pkgsrc/net/wget/work/.destdir` then after a few checks,
164: in your actual prefix like `/usr/pkg`
1.1 schmonz 165: - `make test` run package tests, if they have any
1.2 schmonz 166: - `make package` create a package without installing it, it will
167: install dependencies though
1.1 schmonz 168: - `make replace` upgrade or reinstall the port if already installed
169: - `make deinstall` deinstall the program
1.2 schmonz 170: - `make install` installs from the aforementionned `work/.destdir`
171: to your prefix
172: - `make bin-install` installs a package for the port, locally if
173: previously built or remotely, as defined by BINPKG_SITES in
174: `mk.conf`, you can make a port install dependencies from packages
175: rather than building them with the DEPENDS_TARGET= bin-install
176: in `mk.conf`
1.1 schmonz 177: - `make show-depends` show port dependencies
178: - `make show-options` show various port options, as defined by `options.mk`
179: - `make clean-depends` cleans all port dependencies
180: - `make distclean` remove the source archive
181: - `make package-clean` remove the package
1.2 schmonz 182: - `make distinfo` or `make mdi` to update the `distinfo` file
183: containing file hashes if you have a new distfile or patch
184: - `make print-PLIST` to generate a `PLIST` file from files found
185: in `work/.destdir`
1.1 schmonz 186:
1.2 schmonz 187: You should be aware that there are many make options along with
188: these targets, like
1.1 schmonz 189:
190: - `PKG_DEBUG_LEVEL`
191: - `CHECK_FILES`
192: - and many others described the the NetBSD pkgsrc guide
193:
194:
195: ## pkgsrc configuration
196:
1.2 schmonz 197: The framework uses an `mk.conf` file, usually found in /etc. Here's
198: how mine looks:
1.1 schmonz 199:
1.10 ! schmonz 200: [[!format makefile """
1.1 schmonz 201: # Tue Oct 15 21:21:46 CEST 2013
202:
203: .ifdef BSD_PKG_MK # begin pkgsrc settings
204:
205: DISTDIR= /pkgsrc/distfiles
206: PACKAGES= /pkgsrc/packages
207: WRKOBJDIR= /pkgsc/work
208: ABI= 64
209: PKGSRC_COMPILER= clang
210: CC= clang
211: CXX= clang++
212: CPP= ${CC} -E
213:
214: PKG_DBDIR= /var/db/pkg
215: LOCALBASE= /usr/pkg
216: VARBASE= /var
217: PKG_TOOLS_BIN= /usr/pkg/sbin
218: PKGINFODIR= info
219: PKGMANDIR= man
220: BINPKG_SITES= http://pkgsrc.saveosx.org/Darwin/2013Q4/x86_64
221: DEPENDS_TARGET= bin-install
222: X11_TYPE= modular
223: TOOLS_PLATFORM.awk?= /usr/pkg/bin/nawk
224: TOOLS_PLATFORM.sed?= /usr/pkg/bin/nbsed
225: ALLOW_VULNERABLE_PACKAGES= yes
226: MAKE_JOBS= 8
227: SKIP_LICENSE_CHECK= yes
228: PKG_DEVELOPER= yes
229: SIGN_PACKAGES= gpg
230: PKG_DEFAULT_OPTIONS+= -pulseaudio -x264 -imlib2-amd64 -dconf
231: .endif # end pkgsrc settings
1.4 schmonz 232: """]]
1.1 schmonz 233:
1.2 schmonz 234: - I use `DISTDIR`, `PACKAGES`, `WRKOBJDIR` to move distfiles,
235: packages and source files somewhere else to keep my pkgsrc tree
236: clean
237: - `PKGSRC_COMPILER`, `CC`, `CXX`, `CPP` and `ABI` are my compiler
238: options. I'm using clang to create 64 bit binaries here
239: - `PKG_DBDIR`, `VARBASE`, `LOCALBASE`, `PKG_TOOLS_BIN` are my prefix
240: and package database path and package tools settings
241: - `PKGINFODIR`, `PKGMANDIR` are the info and man directories
242: - `BINPKG_SITES` is the remote place where to get packages with the
243: `bin-install` make target
244: - `DEPENDS_TARGET` is the way port dependencies should be installed.
245: `bin-install` will simply install a package instead of building
246: the port
247: - `X11_TYPE` sould be `native` or `modular`, the latter meaning we
248: want X11 libraries from pkgsrc instead of using the `native` ones
249: usually in `/usr/X11R7` in Linux or BSD systems and `/opt/X11`
250: on Mac OS X with XQuartz
251: - `TOOLS_PLATFORM.*` points to specific programs used by pkgsrc,
252: here I use the one that was generated by pkgsrc bootstrap for
253: maximum compatibility
254: - `ALLOW_VULNERABLE_PACKAGES` allows you to disallow the installation
255: of vulnerable packages in critical environments like servers
256: - `MAKE_JOBS` the number of concurrent make jobs, I set it to 8 but
257: it breaks some ports
258: - `SKIP_LICENSE_CHECK` will skip the license check. If disabled you
259: will have to define a list of licenses you find acceptable with
260: `ACCEPTABLE_LICENSES`
261: - `PKG_DEVELOPER` this option will show more details during the port building
262: - `SIGN_PACKAGES` allows you to `gpg` sign packages. More info in
263: my [blog post](http://saveosx.org/signed-packages/) about it
264: - `PKG_DEFAULT_OPTIONS` allows you to enable or disable specific
265: options for all ports (as defined with ports' options.mk files),
266: I disabled a few options so less ports would break, pulseaudio
267: doesn't build on Mac OS X for example, neither do x264, dconf
1.1 schmonz 268:
1.6 wiki 269: Keep in mind that there are many other available options.
1.1 schmonz 270:
271:
272: ## creating a simple port
273:
1.2 schmonz 274: Let's create a little port using the tools we've talked about above.
275: I will use a little window manager called 2bwm.
276:
277: - We need an url for the program source files archive. It can be a
278: direct link to a tar or xz archive. Mine's
279: `http://pkgsrc.saveosx.org/Darwin/distfiles/2bwm-0.1.tar.gz`
1.1 schmonz 280:
1.2 schmonz 281: - Now that we have a proper link for our program source, create a
282: directory for your port:
1.1 schmonz 283:
284: $ mkdir ~/pkgsrc/wm/2bwm
285:
286: - Use `url2pkg` to create the needed files automatically:
287:
288: $ url2pkg http://pkgsrc.saveosx.org/Darwin/distfiles/2bwm-0.1.tar.gz
289:
1.2 schmonz 290: You'll be presented with a text editor like `vim` to enter basic
291: Makefile options:
1.1 schmonz 292:
1.2 schmonz 293: - `DISTNAME`, `CATEGORIES`, `MASTER_SITES` should be set automatically
294: - enter your mail address for `MAINTAINER` so users know whom to
295: contact if the port is broken
1.1 schmonz 296: - make sure the `HOMEPAGE` is set right, for 2bwm it is a github page
297: - write a `COMMENT`, it should be a one-line description of the program
1.2 schmonz 298: - find out which license the program uses, in my case it is the
299: `isc` license. You can find a list of licenses in `pkgsrc/mk/licenses.mk`.
300: - Below you will see `.include "../../mk/bsd.pkg.mk"` at the end
301: of the Makefile and above this should go the port's needed
302: dependencies to build, we'll leave that empty at the moment and
303: try to figure out what 2bwm needs
304: - exit vim and it should fetch and update the file hashes for you.
305: If it says `permission denied` you can just run `make mdi` to
306: fetch and upadate the `distinfo` file
307:
308: So now you have valid `Makefile` and `distinfo` files but you need
309: to write a paragraph in `DESCR`. You can usually find inspiration
310: on the program's homepage.
1.1 schmonz 311:
1.2 schmonz 312: Here's how they look like at the moment:
1.1 schmonz 313:
1.2 schmonz 314: Makefile:
1.10 ! schmonz 315: [[!format makefile """
1.3 schmonz 316: # [[!paste id=rcsid1]][[!paste id=rcsid2]]
1.1 schmonz 317:
318: DISTNAME= 2bwm-0.1
319: CATEGORIES= wm
320: MASTER_SITES= http://pkgsrc.saveosx.org/Darwin/distfiles/
321:
322: MAINTAINER= yrmt@users.sourceforge.net
323: HOMEPAGE= http://github.com/venam/2bwm/
324: COMMENT= Fast floating WM written over the XCB library and derived from mcwm
325: LICENSE= isc
326:
327: .include "../../mk/bsd.pkg.mk"
1.4 schmonz 328: """]]
1.1 schmonz 329:
330: distinfo:
331:
332:
1.3 schmonz 333: [[!paste id=rcsid1]][[!paste id=rcsid2]]
1.1 schmonz 334:
335: SHA1 (2bwm-0.1.tar.gz) = e83c862dc1d9aa198aae472eeca274e5d98df0ad
336: RMD160 (2bwm-0.1.tar.gz) = d9a93a7d7ae7183f5921f9ad76abeb1401184ef9
337: Size (2bwm-0.1.tar.gz) = 38419 bytes
338:
339: DESCR:
340:
341: A fast floating WM, with the particularity of having 2 borders,
342: written over the XCB library and derived from mcwm written by
343: Michael Cardell. In 2bWM everything is accessible from the keyboard
344: but a pointing device can be used for move, resize and raise/lower.
345:
346: But our PLIST file is still empty.
347:
348:
349: #### build stage
350:
1.2 schmonz 351: Let's try to build the port to see if things work but as soon as
352: the build stage starts, we get this error:
1.1 schmonz 353:
354: > 2bwm.c:26:10: fatal error: 'xcb/randr.h' file not found
355:
1.2 schmonz 356: Let's find out which port provides this file !
1.1 schmonz 357:
1.2 schmonz 358: $ pkgin se xcb
1.1 schmonz 359:
1.2 schmonz 360: returns these possible packages:
1.1 schmonz 361:
362: xcb-util-wm-0.3.9nb1 Client and window-manager helpers for ICCCM and EWMH
363: xcb-util-renderutil-0.3.8nb1 Convenience functions for the Render extension
364: xcb-util-keysyms-0.3.9nb1 XCB Utilities
365: xcb-util-image-0.3.9nb1 XCB port of Xlib's XImage and XShmImage
366: xcb-util-0.3.9nb1 = XCB Utilities
367: xcb-proto-1.9 = XCB protocol descriptions (in XML)
368: xcb-2.4nb1 Extensible, multiple cut buffers for X
369:
1.2 schmonz 370: Package content inspection allowed me to find the right port
1.1 schmonz 371:
372: $ pkgin pc libxcb|grep randr.h
373:
1.2 schmonz 374: So we can add the libxcb `buildlink3.mk` file to the Makefile above
375: the bsd.pkg.mk include:
1.1 schmonz 376:
377: .include "../../x11/libxcb/buildlink3.mk"
378:
1.2 schmonz 379: This allows the port to link 2bwm against the libxcb port. Let's
380: try to build the port again!
1.1 schmonz 381:
382: $ make clean
383: $ make
384:
385: Reports another error !
386:
387: > 2bwm.c:27:10: fatal error: 'xcb/xcb_keysyms.h' file not found
388:
389: It looks like this file is provided by xcb-util-keysyms, so let's add:
390:
391: .include "../../x11/xcb-util-keysyms/buildlink3.mk"
392:
393: in our Makefile.
394:
1.2 schmonz 395: Clean, build again, and add more dependencies until it passes the
396: build stage. Here's how my Makefile ends up looking like:
1.1 schmonz 397:
1.10 ! schmonz 398: [[!format makefile """
1.3 schmonz 399: # [[!paste id=rcsid1]][[!paste id=rcsid2]]
1.1 schmonz 400:
401: DISTNAME= 2bwm-0.1
402: CATEGORIES= wm
403: MASTER_SITES= http://pkgsrc.saveosx.org/Darwin/distfiles/
404:
405: MAINTAINER= yrmt@users.sourceforge.net
406: HOMEPAGE= http://github.com/venam/2bwm/
407: COMMENT= Fast floating WM written over the XCB library and derived from mcwm
408: LICENSE= isc
409:
410: .include "../../x11/libxcb/buildlink3.mk"
411: .include "../../x11/xcb-util-wm/buildlink3.mk"
412: .include "../../x11/xcb-util-keysyms/buildlink3.mk"
413: .include "../../x11/xcb-util/buildlink3.mk"
414: .include "../../mk/bsd.pkg.mk"
1.4 schmonz 415: """]]
1.1 schmonz 416:
417:
418: #### install phase
419:
1.2 schmonz 420: Geat ! We got our program to compile in pkgsrc. Now we must generate
421: the PLIST file so we can actually install the program, but we must
422: `make stage-install` to make sure that it installs in the right
423: place.
1.1 schmonz 424:
425:
426: $ find /pkgsrc/work/wm/2bwm/work/.destdir/
427:
428: returns:
429:
430: /pkgsrc/work/wm/2bwm/work/.destdir/
431: /pkgsrc/work/wm/2bwm/work/.destdir//usr
432: /pkgsrc/work/wm/2bwm/work/.destdir//usr/local
433: /pkgsrc/work/wm/2bwm/work/.destdir//usr/local/bin
434: /pkgsrc/work/wm/2bwm/work/.destdir//usr/local/bin/2bwm
435: /pkgsrc/work/wm/2bwm/work/.destdir//usr/local/bin/hidden
436: /pkgsrc/work/wm/2bwm/work/.destdir//usr/local/share
437: /pkgsrc/work/wm/2bwm/work/.destdir//usr/local/share/man
438: /pkgsrc/work/wm/2bwm/work/.destdir//usr/local/share/man/man1
439: /pkgsrc/work/wm/2bwm/work/.destdir//usr/local/share/man/man1/2bwm.1
440: /pkgsrc/work/wm/2bwm/work/.destdir//usr/local/share/man/man1/hidden.1
441: /pkgsrc/work/wm/2bwm/work/.destdir//usr/pkg
442:
443: This doesn't look right since our `LOCALBASE` is `/usr/pkg`.
444:
445:
446: $ make print-PLIST
447:
1.2 schmonz 448: returns nothing, because 2bwm installs files in the wrong place so
449: we need to fix 2bwm's own Makefile to use the right `DESTDIR` and
450: `PREFIX`, that is set to the right place by pkgsrc. Let's inspect
451: how 2bwm installs:
1.1 schmonz 452:
1.2 schmonz 453: From 2bwm's Makefile:
1.1 schmonz 454:
1.10 ! schmonz 455: [[!format makefile """
1.1 schmonz 456: install: $(TARGETS)
457: test -d $(DESTDIR)$(PREFIX)/bin || mkdir -p $(DESTDIR)$(PREFIX)/bin
458: install -pm 755 2bwm $(DESTDIR)$(PREFIX)/bin
459: install -pm 755 hidden $(DESTDIR)$(PREFIX)/bin
460: test -d $(DESTDIR)$(MANPREFIX)/man1 || mkdir -p $(DESTDIR)$(MANPREFIX)/man1
461: install -pm 644 2bwm.man $(DESTDIR)$(MANPREFIX)/man1/2bwm.1
462: install -pm 644 hidden.man $(DESTDIR)$(MANPREFIX)/man1/hidden.1
1.4 schmonz 463: """]]
1.1 schmonz 464:
1.2 schmonz 465: This looks fine since it installs in a `DESTDIR`/`PREFIX` but it sets
1.1 schmonz 466:
467: > PREFIX=/usr/local
468:
469: and
470:
471: > MANPREFIX=$(PREFIX)/share/man
472:
1.2 schmonz 473: In the beginning of the Makefile. We should remove the first line
474: and edit the man prefix:
1.1 schmonz 475:
476: > MANPREFIX=${PKGMANDIR}
477:
1.2 schmonz 478: so pkgsrc can install the program's files in the right place. We
479: have two ways of modifying this file, either patch the Makefile or
480: use `sed` substitution which is a builtin pkgsrc feature that allows
481: you to change lines in files with a sed command before building the
482: port.
1.1 schmonz 483:
1.2 schmonz 484: I will show how to do both ways so you can get an introduction on
485: how to generate patch files for pkgsrc.
1.1 schmonz 486:
487: #### patching the Makefile :
488:
489: - edit the file you need to modify with `pkgvi`:
490:
491:
492: $ pkgvi /pkgsrc/work/wm/2bwm/work/2bwm-0.1/Makefile
493:
494: which should return:
495:
496: > pkgvi: File was modified. For a diff, type:
497: pkgdiff "/Volumes/Backup/pkgsrc/work/wm/2bwm/work/2bwm-0.1/Makefile"
498:
499: and this returns our diff.
500:
501:
1.2 schmonz 502: - create the patch with `mkpatches`, it should create a `patches`
503: directory in the port containing the patch and an original file
504: removed with `mkpatches -c`.
1.1 schmonz 505:
506: $ find patches/*
507: patches/patch-Makefile
508:
1.2 schmonz 509: - now that the patch has been created, we need to add it's hash to
510: distinfo otherwise pkgsrc won't pick it up:
1.1 schmonz 511:
512: $ make mdi
513: you should get this new line:
514:
515: > SHA1 (patch-Makefile) = 9f8cd00a37edbd3e4f65915aa666ebd0f3c04e04
516:
517:
1.2 schmonz 518: - you can now clean and `make patch` and `make stage-install
519: CHECK_FILES=no` since we still haven't generated a proper PLIST.
520: Let's see if 2wm files were installed in the right place this
521: time:
1.1 schmonz 522:
523: $ find /pkgsrc/work/wm/2bwm/work/.destdir/
524:
525: /pkgsrc/work/wm/2bwm/work/.destdir/
526: /pkgsrc/work/wm/2bwm/work/.destdir//usr
527: /pkgsrc/work/wm/2bwm/work/.destdir//usr/pkg
528: /pkgsrc/work/wm/2bwm/work/.destdir//usr/pkg/bin
529: /pkgsrc/work/wm/2bwm/work/.destdir//usr/pkg/bin/2bwm
530: /pkgsrc/work/wm/2bwm/work/.destdir//usr/pkg/bin/hidden
531:
532: It looks like it is alright ! Let's generate the PLIST:
533:
534: $ make print-PLIST > PLIST
535:
536: containing:
537:
1.3 schmonz 538: @comment [[!paste id=rcsid1]][[!paste id=rcsid2]]
1.1 schmonz 539: bin/2bwm
540: bin/hidden
541:
1.2 schmonz 542: There you have a working port you can install normally with
1.1 schmonz 543:
1.2 schmonz 544: $ make install
1.1 schmonz 545:
546:
547: #### using the sed substitution framework
548:
1.2 schmonz 549: You should be able to fix the prefix error much quicker than with
550: the patching explained above thanks to the sed substitution framework.
551: Here's how it looks like in my port Makefile:
1.1 schmonz 552:
1.10 ! schmonz 553: [[!format makefile """
1.1 schmonz 554: SUBST_CLASSES+= makefile
555: SUBST_STAGE.makefile= pre-build
556: SUBST_MESSAGE.makefile= Fixing makefile
557: SUBST_FILES.makefile= Makefile
558: SUBST_SED.makefile= -e 's,/usr/local,${PREFIX},g'
559: SUBST_SED.makefile+= -e 's,share/man,${PKGMANDIR},g'
1.4 schmonz 560: """]]
1.1 schmonz 561:
1.2 schmonz 562: As you can see, you can do multiple commands on multiple files, it
563: is very useful for very small fixes like this.
1.1 schmonz 564:
565:
566: #### pkglint
567:
1.2 schmonz 568: Now that we have a working port, we must make sure it complies to the pkgsrc rules.
1.1 schmonz 569:
570: $ pkglint
571:
1.2 schmonz 572: Returns
1.1 schmonz 573:
574: ERROR: DESCR:4: File must end with a newline.
575: ERROR: patches/patch-Makefile:3: Comment expected.
576: 2 errors and 0 warnings found. (Use -e for more details.)
577:
578: Fix the things pkglint tells you to do until you get the glorious:
579:
580: > looks fine.
581:
1.2 schmonz 582: Then you should do some testing on the program itelf on at least
583: two platforms such as NetBSD, Mac OS X. Other platforms supported
584: by pkgsrc can be found at [pkgsrc.org](http://pkgsrc.org). If you
585: would like to submit your pkgsrc upstream you can either subscribe
586: to pkgsrc-wip or ask a NetBSD developer to add it for you.
587:
588: You can find the 2bwm port I submitted in
589: [pkgsrc-wip](http://pkgsrc-wip.cvs.sourceforge.net/viewvc/pkgsrc-wip/wip/2bwm/).
590:
591:
592: ## pkgsrc and wip
593:
594: If you want to submit your port for others to use you can either
1.6 wiki 595: subscribe to pkgsrc-wip or ask a NetBSD developer to add it for you.
1.2 schmonz 596:
597: pkgsrc-wip is hosted on
598: [sourceforge](https://sourceforge.net/projects/pkgsrc-wip/) and you
599: can easily get cvs access to it if you create an account on there
600: and send an email to NetBSD developer `@wiz` (Thomas Klausner)
1.6 wiki 601: asking nicely for commit access.
1.1 schmonz 602:
603:
604: ## the options framework
605:
606: You can create port options with the `options.mk` file, like for `wm/dwm`
607:
608:
1.10 ! schmonz 609: [[!format makefile """
1.3 schmonz 610: # [[!paste id=rcsid1]][[!paste id=rcsid2]]
1.1 schmonz 611:
612: PKG_OPTIONS_VAR= PKG_OPTIONS.dwm
613: PKG_SUPPORTED_OPTIONS= xinerama
614: PKG_SUGGESTED_OPTIONS= xinerama
615:
616: .include "../../mk/bsd.options.mk"
617:
618: #
619: # Xinerama support
620: #
621: # If we don't want the Xinerama support we delete XINERAMALIBS and
622: # XINERAMAFLAGS lines, otherwise the Xinerama support is the default.
623: #
624: .if !empty(PKG_OPTIONS:Mxinerama)
625: . include "../../x11/libXinerama/buildlink3.mk"
626: .else
627: SUBST_CLASSES+= options
628: SUBST_STAGE.options= pre-build
629: SUBST_MESSAGE.options= Toggle the Xinerama support
630: SUBST_FILES.options= config.mk
631: SUBST_SED.options+= -e '/^XINERAMA/d'
632: . include "../../x11/libX11/buildlink3.mk"
633: .endif
1.4 schmonz 634: """]]
1.1 schmonz 635:
636: This file should be included in the Makefile:
637:
638: .include "options.mk"
639:
640: If you type `make show-options`, you should see this:
641:
642: Any of the following general options may be selected:
643: xinerama Enable Xinerama support.
644:
645: These options are enabled by default:
646: xinerama
647:
648: These options are currently enabled:
649: xinerama
650:
651: You can select which build options to use by setting PKG_DEFAULT_OPTIONS
652: or PKG_OPTIONS.dwm.
653:
654: Running `make PKG_OPTIONS=""` should build without the `xinerama` dwm option enabled by default.
655:
656: The options.mk file must contain these variables:
657:
658: - `PKG_OPTIONS_VAR` sets the options variable name
659: - `PKG_SUPPORTED_OPTIONS` lists all available options
660: - `PKG_SUGGESTED_OPTIONS` lists options enabled by default
661:
662: It allows you to change configure arguments and include other buildlinks, and various other settings.
663:
664:
665: ## hosting a package repo
666:
1.2 schmonz 667: Now that you've created a few ports, you might want to make precompiled
668: packages available for testing. You will need pkgsrc's `pkg_install`
669: on the host system. I host my [packages](http://pkgsrc.saveosx.org/)
670: on a FreeBSD server with a bootstrapped pkgsrc.
1.1 schmonz 671:
1.9 wiki 672: use this shell function to :
1.1 schmonz 673:
1.8 wiki 674: [[!format sh """
1.1 schmonz 675: add () {
676: # upload the package to remote server
1.9 wiki 677: scp $1 youri@saveosx.org:/usr/local/www/saveosx/packages/Darwin/2013Q4/x86_64/All/ 2> /dev/null
1.1 schmonz 678:
679: # update the package summary
1.9 wiki 680: ssh youri@saveosx.org 'cd /usr/local/www/saveosx/packages/Darwin/2013Q4/x86_64/All/;
1.1 schmonz 681: rm pkg_summary.gz;
682: /usr/pkg/sbin/pkg_info -X *.tgz | gzip -9 > pkg_summary.gz'
683:
684: # pkgin update
685: sudo pkgin update
686: }
1.4 schmonz 687: """]]
1.1 schmonz 688:
1.2 schmonz 689: - upload a package
690: - update the package summary, which is an archive containing
691: information about all present packages that will be picked up by
692: pkg_install and pkgin. It looks like this for one package:
1.1 schmonz 693:
694: PKGNAME=osxinfo-0.1
695: DEPENDS=sqlite3>=3.7.16.2nb1
696: COMMENT=Small Mac OS X Info Program
697: SIZE_PKG=23952
698: BUILD_DATE=2014-06-29 12:45:08 +0200
699: CATEGORIES=misc
700: HOMEPAGE=http://github.com/yrmt/osxinfo
701: LICENSE=isc
702: MACHINE_ARCH=x86_64
703: OPSYS=Darwin
704: OS_VERSION=14.0.0
705: PKGPATH=wip/osxinfo
706: PKGTOOLS_VERSION=20091115
707: REQUIRES=/System/Library/Frameworks/CoreFoundation.framework/Versions/A/CoreFoundation
708: REQUIRES=/System/Library/Frameworks/Foundation.framework/Versions/C/Foundation
709: REQUIRES=/System/Library/Frameworks/IOKit.framework/Versions/A/IOKit
710: REQUIRES=/usr/lib/libSystem.B.dylib
711: REQUIRES=/usr/pkg/lib/libsqlite3.0.dylib
712: FILE_NAME=osxinfo-0.1.tgz
713: FILE_SIZE=9710
1.7 wiki 714: DESCRIPTION=Small and fast Mac OS X info program written in C.
1.1 schmonz 715: DESCRIPTION=
716: DESCRIPTION=Homepage:
717: DESCRIPTION=http://github.com/yrmt/osxinfo
718:
719:
1.2 schmonz 720: - update pkgin
1.1 schmonz 721:
722:
1.2 schmonz 723: And this shell alias to upload all my built packages, but I still
724: need to run `add()` mentionned above to update the pkg_summary
1.1 schmonz 725:
1.8 wiki 726: [[!format sh """
1.9 wiki 727: up='rsync -avhz --progress /pkgsrc/packages/ youri@saveosx.org:/usr/local/www/saveosx/packages/Darwin/2013Q4/x86_64/'
1.4 schmonz 728: """]]
1.1 schmonz 729:
1.2 schmonz 730: Then you should be able to set the url in repositories.conf to use
731: your packages with pkgin. You can also install them directly with
732: something like `pkg_add
733: http://pkgsrc.saveosx.org/Darwin/2013Q4/x86_64/All/9menu-1.8nb1.tgz` of
734: course.
1.1 schmonz 735:
736:
737: ## build all packages
738:
1.6 wiki 739: see jperkin's excellent blog
1.2 schmonz 740: [posts](http://www.perkin.org.uk/posts/distributed-chrooted-pkgsrc-bulk-builds.html)
741: about this.
1.1 schmonz 742:
743:
744: ## faq
745:
746: #### what if the port I'm making is a dependency for another one?
747:
1.2 schmonz 748: You should just generate the buildlink3.mk file we've talked about
749: earlier like this:
1.1 schmonz 750:
751: $ createbuildlink > buildlink3.mk
752:
753: #### what if the program is only hosted on GitHub ?
754:
1.2 schmonz 755: pkgsrc supports fetching archives from specific git commits on
756: GitHub like this:
1.10 ! schmonz 757: [[!format makefile """
1.1 schmonz 758: PKGNAME= 2bwm-0.1
759: CATEGORIES= wm
760: GHCOMMIT= 52a097ca644eb571b22a135951c945fcca57a25c
761: DISTNAME= ${GHCOMMIT}
762: MASTER_SITES= https://github.com/venam/2bwm/archive/
763: DIST_SUBDIR= 2bwm
764: WRKSRC= ${WRKDIR}/2bwm-${GHCOMMIT}
1.4 schmonz 765: """]]
1.1 schmonz 766:
1.2 schmonz 767: You can then easily update the git commit and the distinfo with it
768: to update the program.
1.1 schmonz 769:
770: #### what if the program doesn't have a Makefile
771:
1.2 schmonz 772: You can do all Makefile operations directly from the port's Makefile
773: like this:
1.1 schmonz 774:
775:
1.10 ! schmonz 776: [[!format makefile """
1.1 schmonz 777: post-extract:
778: ${CHMOD} a-x ${WRKSRC}/elementary/apps/48/internet-mail.svg
779:
780: do-install:
781: ${INSTALL_DATA_DIR} ${DESTDIR}${PREFIX}/share/icons
782: cd ${WRKSRC} && pax -rw -pe . ${DESTDIR}${PREFIX}/share/icons/
1.4 schmonz 783: """]]
1.1 schmonz 784:
1.2 schmonz 785: To install, but you can also build programs from the Makefile. This
786: is what qt4-sqlite3 uses:
1.1 schmonz 787:
1.10 ! schmonz 788: [[!format makefile """
1.1 schmonz 789: do-build:
790: cd ${WRKSRC}/src/tools/bootstrap && env ${MAKE_ENV} ${GMAKE}
791: cd ${WRKSRC}/src/tools/moc && env ${MAKE_ENV} ${GMAKE}
792: cd ${WRKSRC}/src/plugins/sqldrivers/sqlite && env ${MAKE_ENV} ${GMAKE}
1.4 schmonz 793: """]]
1.1 schmonz 794:
795:
1.2 schmonz 796: You can install the following type of files:
1.1 schmonz 797:
798: `INSTALL_PROGRAM_DIR` : directories that contain binaries
799:
800: `INSTALL_SCRIPT_DIR` : directories that contain scripts
801:
802: `INSTALL_LIB_DIR` : directories that contain shared and static libraries
803:
804: `INSTALL_DATA_DIR`: directories that contain data files
805:
806: `INSTALL_MAN_DIR` : directories that contain man pages
807:
808: `INSTALL_PROGRAM` : binaries that can be stripped from debugging symbols
809:
810: `INSTALL_SCRIPT` : binaries that cannot be stripped
811:
812: `INSTALL_GAME` : game binaries
813:
814: `INSTALL_LIB` : shared and static libraries
815:
816: `INSTALL_DATA` : data files
817:
818: `INSTALL_GAME_DATA` : data files for games
819:
820: `INSTALL_MAN` : man pages
821:
822:
1.2 schmonz 823: `INSTALLATION_DIRS` : A list of directories relative to PREFIX that
824: are created by pkgsrc at the beginning of the install phase. The
825: package is supposed to create all needed directories itself before
826: installing files to it and list all other directories here.
1.1 schmonz 827:
828: #### common errors
829:
830: - > Makefile:19: *** missing separator. Stop.
831:
1.2 schmonz 832: This means you're not using the right `make`. On most systems, the
833: make installed from the pkgsrc bootstrap is called `bmake`
1.1 schmonz 834:
1.2 schmonz 835: - If you have a feeling a port is stuck in the building stage,
836: disable make jobs in your mk.conf
1.1 schmonz 837:
838:
1.3 schmonz 839: [[!cut id=rcsid1 text="$Net"]]
840: [[!cut id=rcsid2 text="BSD$"]]
1.2 schmonz 841: [[!meta title="An introduction to packaging"]]
1.1 schmonz 842: [[!meta author="Youri Mouton"]]
CVSweb for NetBSD wikisrc <wikimaster@NetBSD.org> software: FreeBSD-CVSweb
![[BACK]](/icons/back.gif){kind=icon}
Return to intro_to_packaging.mdwn CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [NetBSD Developer Wiki] / wikisrc / pkgsrc