diff --git a/documentation/content/en/books/porters-handbook/porting-samplem/chapter.adoc b/documentation/content/en/books/porters-handbook/porting-samplem/chapter.adoc index 1196dc5813..9a7dbc37a2 100644 --- a/documentation/content/en/books/porters-handbook/porting-samplem/chapter.adoc +++ b/documentation/content/en/books/porters-handbook/porting-samplem/chapter.adoc @@ -1,125 +1,124 @@ --- title: Chapter 14. A Sample Makefile prev: books/porters-handbook/porting-dads next: books/porters-handbook/order --- [[porting-samplem]] = A Sample [.filename]#Makefile# :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :skip-front-matter: :xrefstyle: basic :relfileprefix: ../ :outfilesuffix: :sectnumoffset: 14 include::shared/mirrors.adoc[] include::shared/authors.adoc[] include::shared/releases.adoc[] include::shared/en/mailing-lists.adoc[] include::shared/en/teams.adoc[] include::shared/en/urls.adoc[] toc::[] Here is a sample [.filename]#Makefile# that can be used to create a new port. Make sure to remove all the extra comments (ones between brackets). The format shown is the recommended one for ordering variables, empty lines between sections, and so on. This format is designed so that the most important information is easy to locate. We recommend using <> to check the [.filename]#Makefile#. [.programlisting] .... -[the header...just to make it easier for us to identify the ports.] # $FreeBSD$ [ ^^^^^^^^^ This will be automatically replaced with RCS ID string by SVN when it is committed to our repository. If upgrading a port, do not alter this line back to "$FreeBSD$". SVN deals with it automatically.] [section to describe the port itself and the master site - PORTNAME and PORTVERSION or the DISTVERSION* variables are always first, followed by CATEGORIES, and then MASTER_SITES, which can be followed by MASTER_SITE_SUBDIR. PKGNAMEPREFIX and PKGNAMESUFFIX, if needed, will be after that. Then comes DISTNAME, EXTRACT_SUFX and/or DISTFILES, and then EXTRACT_ONLY, as necessary.] PORTNAME= xdvi DISTVERSION= 18.2 CATEGORIES= print [do not forget the trailing slash ("/")! if not using MASTER_SITE_* macros] MASTER_SITES= ${MASTER_SITE_XCONTRIB} MASTER_SITE_SUBDIR= applications PKGNAMEPREFIX= ja- DISTNAME= xdvi-pl18 [set this if the source is not in the standard ".tar.gz" form] EXTRACT_SUFX= .tar.Z [section for distributed patches -- can be empty] PATCH_SITES= ftp://ftp.sra.co.jp/pub/X11/japanese/ PATCHFILES= xdvi-18.patch1.gz xdvi-18.patch2.gz [If the distributed patches were not made relative to ${WRKSRC}, this may need to be tweaked] PATCH_DIST_STRIP= -p1 [maintainer; *mandatory*! This is the person who is volunteering to handle port updates, build breakages, and to whom a users can direct questions and bug reports. To keep the quality of the Ports Collection as high as possible, we do not accept new ports that are assigned to "ports@FreeBSD.org".] MAINTAINER= asami@FreeBSD.org COMMENT= DVI Previewer for the X Window System [license -- should not be empty] LICENSE= BSD2CLAUSE LICENSE_FILE= ${WRKSRC}/LICENSE [dependencies -- can be empty] RUN_DEPENDS= gs:print/ghostscript [If it requires GNU make, not /usr/bin/make, to build...] USES= gmake [If it is an X application and requires "xmkmf -a" to be run...] USES= imake [this section is for other standard bsd.port.mk variables that do not] belong to any of the above] [If it asks questions during configure, build, install...] IS_INTERACTIVE= yes [If it extracts to a directory other than ${DISTNAME}...] WRKSRC= ${WRKDIR}/xdvi-new [If it requires a "configure" script generated by GNU autoconf to be run] GNU_CONFIGURE= yes [et cetera.] [If it requires options, this section is for options] OPTIONS_DEFINE= DOCS EXAMPLES FOO OPTIONS_DEFAULT= FOO [If options will change the files in plist] OPTIONS_SUB=yes FOO_DESC= Enable foo support FOO_CONFIGURE_ENABLE= foo [non-standard variables to be used in the rules below] MY_FAVORITE_RESPONSE= "yeah, right" [then the special rules, in the order they are called] pre-fetch: i go fetch something, yeah post-patch: i need to do something after patch, great pre-install: and then some more stuff before installing, wow [and then the epilogue] .include .... diff --git a/documentation/content/en/books/porters-handbook/quick-porting/chapter.adoc b/documentation/content/en/books/porters-handbook/quick-porting/chapter.adoc index 48d0cef894..08f96c6dab 100644 --- a/documentation/content/en/books/porters-handbook/quick-porting/chapter.adoc +++ b/documentation/content/en/books/porters-handbook/quick-porting/chapter.adoc @@ -1,284 +1,279 @@ --- title: Chapter 3. Quick Porting prev: books/porters-handbook/new-port next: books/porters-handbook/slow-porting --- [[quick-porting]] = Quick Porting :doctype: book :toc: macro :toclevels: 1 :icons: font :sectnums: :sectnumlevels: 6 :source-highlighter: rouge :experimental: :skip-front-matter: :xrefstyle: basic :relfileprefix: ../ :outfilesuffix: :sectnumoffset: 3 include::shared/mirrors.adoc[] include::shared/authors.adoc[] include::shared/releases.adoc[] include::shared/en/mailing-lists.adoc[] include::shared/en/teams.adoc[] include::shared/en/urls.adoc[] toc::[] This section describes how to quickly create a new port. For applications where this quick method is not adequate, the full "Slow Porting" process is described in <>. First, get the original tarball and put it into `DISTDIR`, which defaults to [.filename]#/usr/ports/distfiles#. [NOTE] ==== These steps assume that the software compiled out-of-the-box. In other words, absolutely no changes were required for the application to work on a FreeBSD system. If anything had to be changed, refer to <>. ==== [NOTE] ==== It is recommended to set the `DEVELOPER` man:make[1] variable in [.filename]#/etc/make.conf# before getting into porting. [source,bash] .... # echo DEVELOPER=yes >> /etc/make.conf .... This setting enables the "developer mode" that displays deprecation warnings and activates some further quality checks on calling `make`. ==== [[porting-makefile]] == Writing the [.filename]#Makefile# The minimal [.filename]#Makefile# would look something like this: [.programlisting] .... # $FreeBSD$ PORTNAME= oneko DISTVERSION= 1.1b CATEGORIES= games MASTER_SITES= ftp://ftp.cs.columbia.edu/archives/X11R5/contrib/ MAINTAINER= youremail@example.com COMMENT= Cat chasing a mouse all over the screen .include .... -[NOTE] -==== -In some cases, the [.filename]#Makefile# of an existing port may contain additional lines in the header, such as the name of the port and the date it was created. This additional information has been declared obsolete, and is being phased out. -==== - Try to figure it out. Do not worry about the contents of the `$FreeBSD$` line, it will be filled in automatically by Subversion when the port is imported to our main ports tree. A more detailed example is shown in the <> section. [[porting-desc]] == Writing the Description Files There are two description files that are required for any port, whether they actually package or not. They are [.filename]#pkg-descr# and [.filename]#pkg-plist#. Their [.filename]#pkg-# prefix distinguishes them from other files. [[porting-pkg-descr]] === [.filename]#pkg-descr# This is a longer description of the port. One to a few paragraphs concisely explaining what the port does is sufficient. [NOTE] ==== This is _not_ a manual or an in-depth description on how to use or compile the port! _Please be careful when copying from the [.filename]#README# or manpage_. Too often they are not a concise description of the port or are in an awkward format. For example, manpages have justified spacing, which looks particularly bad with monospaced fonts. On the other hand, the content of [.filename]#pkg-descr# must be longer than the <> line from the Makefile. It must explain in more depth what the port is all about. ==== A well-written [.filename]#pkg-descr# describes the port completely enough that users would not have to consult the documentation or visit the website to understand what the software does, how it can be useful, or what particularly nice features it has. Mentioning certain requirements like a graphical toolkit, heavy dependencies, runtime environment, or implementation languages help users decide whether this port will work for them. Include a URL to the official WWW homepage. Prepend _one_ of the websites (pick the most common one) with `WWW:` (followed by single space) so that automated tools will work correctly. If the URI is the root of the website or directory, it must be terminated with a slash. [NOTE] ==== If the listed webpage for a port is not available, try to search the Internet first to see if the official site moved, was renamed, or is hosted elsewhere. ==== This example shows how [.filename]#pkg-descr# looks: [.programlisting] .... This is a port of oneko, in which a cat chases a poor mouse all over the screen. : (etc.) WWW: http://www.oneko.org/ .... [[porting-pkg-plist]] === [.filename]#pkg-plist# This file lists all the files installed by the port. It is also called the "packing list" because the package is generated by packing the files listed here. The pathnames are relative to the installation prefix (usually [.filename]#/usr/local#). Here is a small example: [.programlisting] .... bin/oneko man/man1/oneko.1.gz lib/X11/app-defaults/Oneko lib/X11/oneko/cat1.xpm lib/X11/oneko/cat2.xpm lib/X11/oneko/mouse.xpm .... Refer to the man:pkg-create[8] manual page for details on the packing list. [NOTE] ==== It is recommended to keep all the filenames in this file sorted alphabetically. It will make verifying changes when upgrading the port much easier. ==== [TIP] ==== Creating a packing list manually can be a very tedious task. If the port installs a large numbers of files, crosref:plist[plist-autoplist,creating the packing list automatically] might save time. ==== There is only one case when [.filename]#pkg-plist# can be omitted from a port. If the port installs just a handful of files, list them in `PLIST_FILES`, within the port's [.filename]#Makefile#. For instance, we could get along without [.filename]#pkg-plist# in the above [.filename]#oneko# port by adding these lines to the [.filename]#Makefile#: [.programlisting] .... PLIST_FILES= bin/oneko \ man/man1/oneko.1.gz \ lib/X11/app-defaults/Oneko \ lib/X11/oneko/cat1.xpm \ lib/X11/oneko/cat2.xpm \ lib/X11/oneko/mouse.xpm .... [NOTE] ==== Usage of `PLIST_FILES` should not be abused. When looking for the origin of a file, people usually try to grep through the [.filename]#pkg-plist# files in the ports tree. Listing files in `PLIST_FILES` in the [.filename]#Makefile# makes that search more difficult. ==== [TIP] ==== If a port needs to create an empty directory, or creates directories outside of [.filename]#${PREFIX}# during installation, refer to <> for more information. ==== [TIP] ==== As `PLIST_FILES` is a man:make[1] variable, any entry with spaces must be quoted. For example, if using keywords described in man:pkg-create[8] and <>, the entry must be quoted. [.programlisting] .... PLIST_FILES= "@sample ${ETCDIR}/oneko.conf.sample" .... ==== Later we will see how [.filename]#pkg-plist# and `PLIST_FILES` can be used to fulfill <>. [[porting-checksum]] == Creating the Checksum File Just type `make makesum`. The ports framework will automatically generate [.filename]#distinfo#. Do not try to generate the file manually. [[porting-testing]] == Testing the Port Make sure that the port rules do exactly what is desired, including packaging up the port. These are the important points to verify: * [.filename]#pkg-plist# does not contain anything not installed by the port. * [.filename]#pkg-plist# contains everything that is installed by the port. * The port can be installed using the `install` target. This verifies that the install script works correctly. * The port can be deinstalled properly using the `deinstall` target. This verifies that the deinstall script works correctly. * The port only has access to network resources during the `fetch` target phase. This is important for package builders, such as package:ports-mgmt/poudriere[]. * Make sure that `make package` can be run as a normal user (that is, not as `root`). If that fails, the software may need to be patched. See also <> and <>. [.procedure] .Procedure: Recommended Test Ordering . `make stage` . `make stage-qa` . `make package` . `make install` . `make deinstall` . `make package` (as user) Make certain no warnings are shown in any of the stages. Thorough automated testing can be done with package:ports-mgmt/poudriere[] from the Ports Collection, see <> for more information. It maintains `jails` where all of the steps shown above can be tested without affecting the state of the host system. [[porting-portlint]] == Checking the Port with `portlint` Please use `portlint` to see if the port conforms to our guidelines. The package:ports-mgmt/portlint[] program is part of the ports collection. In particular, check that the <> is in the right shape and the <> is named appropriately. [IMPORTANT] ==== Do not blindly follow the output of `portlint`. It is a static lint tool and sometimes gets things wrong. ==== [[porting-submitting]] == Submitting the New Port Before submitting the new port, read the <> section. Once happy with the port, the only thing remaining is to put it in the main FreeBSD ports tree and make everybody else happy about it too. [IMPORTANT] ==== We do not need the [.filename]#work# directory or the [.filename]#pkgname.txz# package, so delete them now. ==== Next, create a man:patch[1], file. Assuming the port is called `oneko` and is in the `games` category. [[porting-submitting-diff]] .Creating a [.filename]#.diff# for a New Port [example] ==== Add all the files with `svn add`. `cd` to the base of the ports tree so full paths to the changed files are included in the diff, then generate the diff with `svn diff`. For example: [source,bash] .... % svn add . % cd ../.. % svn diff games/oneko > oneko.diff .... [IMPORTANT] **** To make it easier for committers to apply the patch on their working copy of the ports tree, please generate the [.filename]#.diff# from the base of your ports tree. **** ==== Submit [.filename]#oneko.diff# with the https://bugs.freebsd.org/submit/[bug submission form]. Use product "Ports & Packages", component "Individual Port(s)", and follow the guidelines shown there. Add a short description of the program to the Description field of the PR (perhaps a short version of `COMMENT`), and remember to add [.filename]#oneko.diff# as an attachment. [NOTE] ==== Giving a good description in the summary of the problem report makes the work of port committers and triagers a lot easier. The expected format for new ports is "[NEW PORT] _category/portname short description of the port_" for new ports. Using this scheme makes it easier and faster to begin the work of committing the new port. ==== After submitting the port, please be patient. The time needed to include a new port in FreeBSD can vary from a few days to a few months. A simple search form of the Problem Report database can be searched at https://bugs.freebsd.org/bugzilla/query.cgi[]. To get a listing of _open_ port PRs, select _Open_ and _Ports & Packages_ in the search form, then click btn:[Search]. After looking at the new port, we will reply if necessary, and commit it to the tree. The submitter's name will also be added to the list of link:{contributors}#contrib-additional[Additional FreeBSD Contributors] and other files. It is also possible to submit ports using a man:shar[1] file. Using the previous example with the `oneko` port above. .Creating a [.filename]#.shar# for a New Port [[porting-submitting-shar]] [example] ==== go to the directory above where the port directory is located, and use `tar` to create the shar archive: [source,bash] .... % cd .. % tar cf oneko.shar --format shar oneko .... ==== [.filename]#oneko.shar# can then be submitted in the same way as [.filename]#oneko.diff# above.