From ba7a78b5e62f0475701965f1a3c00e9f6a8ab3d9 Mon Sep 17 00:00:00 2001 From: Fun Date: Sat, 3 Mar 2018 17:06:56 +0200 Subject: [PATCH 2/2] add Pkgfile manual Almost all the text is from https://crux.nu/Main/Handbook3-3 and https://crux.nu/Main/PortGuidelines --- Makefile | 5 +- Pkgfile.5.in | 194 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 197 insertions(+), 2 deletions(-) create mode 100644 Pkgfile.5.in diff --git a/Makefile b/Makefile index 62f3ef8..451ed05 100644 --- a/Makefile +++ b/Makefile @@ -2,7 +2,7 @@ # pkgutils # # Copyright (c) 2000-2005 by Per Liden -# Copyright (c) 2006-2017 by CRUX team (http://crux.nu) +# Copyright (c) 2006-2018 by CRUX team (http://crux.nu) # # This program is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by @@ -38,7 +38,7 @@ LDFLAGS += -static $(LIBARCHIVELIBS) OBJECTS = main.o pkgutil.o pkgadd.o pkgrm.o pkginfo.o -MANPAGES = pkgadd.8 pkgrm.8 pkginfo.8 pkgmk.8 rejmerge.8 pkgmk.conf.5 +MANPAGES = pkgadd.8 pkgrm.8 pkginfo.8 pkgmk.8 rejmerge.8 pkgmk.conf.5 Pkgfile.5 all: pkgadd pkgmk rejmerge man @@ -88,6 +88,7 @@ install: all install -D -m0644 pkgmk.8 $(DESTDIR)$(MANDIR)/man8/pkgmk.8 install -D -m0644 rejmerge.8 $(DESTDIR)$(MANDIR)/man8/rejmerge.8 install -D -m0644 pkgmk.conf.5 $(DESTDIR)$(MANDIR)/man5/pkgmk.conf.5 + install -D -m0644 Pkgfile.5 $(DESTDIR)$(MANDIR)/man5/Pkgfile.5 ln -sf pkgadd $(DESTDIR)$(BINDIR)/pkgrm ln -sf pkgadd $(DESTDIR)$(BINDIR)/pkginfo diff --git a/Pkgfile.5.in b/Pkgfile.5.in new file mode 100644 index 0000000..3e007f5 --- /dev/null +++ b/Pkgfile.5.in @@ -0,0 +1,194 @@ +.TH Pkgfile 5 "" "pkgutils #VERSION#" "" +.SH NAME +\fBPkgfile\fP \- Build file for pkgmk. +.SH DESCRIPTION +\fBPkgfile\fP defines the build process of a port. +.SH FILE FORMAT +The file is a bash(1) script, which defines a number of variables +(\fIname\fP, \fIversion\fP, \fIrelease\fP and \fIsource\fP) and a function +(\fIbuild\fP) that should be executed in order to compile the package. +.PP +.SS Example: + +.EX +# Description: A library for demonstrating how to create delicious ports. +# URL: http://www.gnu.org/software/somelib/index.html +# Maintainer: Joe Maintainer, joe at myfantasticisp dot net +# Depends on: someotherlib coolness + +name=somelib +version=1.2.3 +release=1 +source=(ftp://ftp.gnu.org/gnu/$name/$name-$version.tar.gz Makefile.in.patch) + +build() { + cd $name-$version + patch -p1 < ../Makefile.in.patch + ./configure --prefix=/usr + make + make DESTDIR=$PKG install + rm -rf $PKG/usr/info +} +.EE + +Note that you should use this specific format for the email address if +you want to put your ports in any of the official CRUX repositories. + +.SS General guidelines +The name of a package should always be lowercase (e.g. \fBname=eterm\fP and +not \fBname=Eterm\fP). In case the package is added to the CRUX ports system +the exact same name should be use for the name of the directory in the +ports structure, i.e. \fI/usr/ports/???/eterm\fP. +.LP +Do not combine several separately distributed programs/libraries into +one package. Make several packages instead. +.LP +Use \fBprtverify\fP to check the port. + +.SS Directories +In general packages should install files in these directories. Exceptions +are of course allowed if there is a good reason. But try to follow the +following directory structure as close as possible. + +.EX +Directory Description +--------- ------------ +/usr/bin/ User command/application binaries +/usr/sbin/ System binaries (e.g. daemons) +/usr/lib/ Libraries +/usr/include/ Header files +/usr/lib// Plug-ins, addons, etc +/usr/share/man/ Man pages +/usr/share// Data files +/usr/etc// Configuration files +/etc/ Configuration files for system software (daemons, etc) +.EE +.LP +\fI/opt\fP directory is reserved for manually compiled/installed +applications. Packages should never place anything there. +.LP +\fI/usr/libexec/\fP is not used in CRUX, thus packages should never +install anything there. Use \fI/usr/lib//\fP instead. + +.SS Junk files +.LP +Packages should not contain "junk files". This includes info pages +and other online documentation, man pages excluded (e.g. \fIusr/doc/*\fP, +\fIREADME\fP, \fI*.info\fP, \fI*.html\fP, etc). +.LP +Files related to NLS (national language support), always use \fB--disable-nls\fP when available. +.LP +Useless or obsolete binaries (e.g. \fI/usr/games/banner\fP and \fI/sbin/mkfs.minix\fP). +.LP + +.SS Variable names +.LP +Do not add new variables to the \fBPkgfile\fP. Only in very few cases +does this actually improve the readability or the quality of the +package. Further, the only variables that are guranteed to work with +future versions of \fBpkgmk\fP are \fIname\fP, \fIversion\fP, \fIrelease\fP, +and \fIsource\fP. Other names could be in conflict with internal variables +in \fBpkgmk\fP. +.LP +Use the \fI$name\fP and \fI$version\fP variables to make the +package easier to update/maintain. For example, + +.EX + source=(http://xyz.org/$name-$version.tar.gz) +.EE + +is better than + +.EX + source=(http://xyz.org/myprog-1.0.3.tar.gz) +.EE + +since the URL will automatically updated when you modify the \fI$version\fP variable. + +.SS Header + +Provide a header including the following fields: + +.EX +Name Meaning +---- ------- +Description A short description of the package; keep it factual +Maintainer Your full name and e-mail address, obfuscated if you want +Packager The original packager's full name and e-mail address +URL A webpage with more information on this software package +Depends on A list of dependencies, separated either by spaces or commas +.EE + +\fIDepends on\fP can be omitted if there are no dependencies. + +.SS Dependencies + +Dependencies are supported by some CRUX tools like \fBprt-get\fP and \fBpkg-get\fP, +the following rules should be respected: + +.IP "" 4 +We list all runtime dependencies except for gcc (libstdc++) and glibc. +.IP "" 4 +\fBcore\fP contains essential packages for a CRUX system, and our scripts +and ports expect the programs provided by \fBcore\fP to be installed; this +means that: +.IP "" 8 +build dependencies provided by \fBcore\fP are not listed in the dependency header +.IP "" 8 +run-time dependencies from \fBcore\fP which aren't dynamically linked in are not to be listed, either +.TP +Examples: +.IP "" 4 +\fBopt/sloccount\fP does \fBnot\fP list \fIperl\fP, because the program is a perl script -- there's no binary that links to \fIlibperl\fP +.IP "" 4 +\fBopt/libxml2\fP \fBdoes\fP list \fIzlib\fP, because \fIlibxml\fP is linked to \fIlibz\fP. +.LP +The reasoning for this policy is that you can use \fBrevdep\fP to find ports +that need to be updated if one of the dependent libraries has become +binary incompatible. To find out what libraries a binary is linked to, +use \fBldd\fP or \fBfinddeps\fP. + +.SS rc start scripts + +You can use the following template script for ports, that provide some +sort of daemon that should be runnable from a script called \fI$name.rc\fP, +your port installed to \fI/etc/rc.d/$name\fP. The installation can happen by +calling the following in your \fibuild()\fP function: + +.EX + install -D -m 755 $SRC/$name.rc $PKG/etc/rc.d/$name +.EE +.SH ENVIRONMENT +.LP +The \fIbuild\fP function should use the \fI$SRC\fP variable whenever it needs +to access the files listed in the source variable, and the \fI$PKG\fP +variable as the root destination of the output files. +.LP +Being a shell script executed in the context of pkgmk(8), the +entire \fBPkgfile\fP file has access to the variables initialized +in pkgmk.conf(5) and the default values set by pkgmk(8). Also, as an +undocumented side effect of how it is used by pkgmk(8), it can also +change the behaviour of pkgmk(8) by rewriting some of its functions +and variables while the current package is built. However, the \fIbuild\fP +function has only read access to these mentioned above. +.SH ERRORS +.LP +Most of the command failures in \fIbuild()\fP will stop +the build process. There is no need to explicitly check the return +codes. If you need/want to handle a command failure you should use +constructs like: + +.EX + \fBif ! command...; then ...\fP + \fBcommand || ...\fP +.EE +.SH SEE ALSO +pkgmk(8), pkgmk.conf(5), +.UR https://crux.nu/Main/PortGuidelines +.UE , +.UR https://crux.nu/Main/PrePostInstallGuidelines +.UE . +.SH COPYRIGHT +pkgmk (pkgutils) is Copyright (c) 2000-2005 Per Liden and Copyright (c) 2006-2018 CRUX team (http://crux.nu). +pkgmk (pkgutils) is licensed through the GNU General Public License. +Read the COPYING file for the complete license. -- 2.15.1