mirror of
https://github.com/macports/macports-guide.git
synced 2026-07-12 18:18:46 -07:00
Boey Maun Suang
321c4fa5f3
* Replace instances of "Darwinports" with "MacPorts", "dport" with "mport", "CVS" with "Subversion" and "cvs" with "svn"; * Update some of the old email address and links; * Make one update about MacPorts no longer supporting OSes other than Mac OS 10.3 and above. git-svn-id: https://svn.macports.org/repository/macports/trunk/doc@26404 d073be05-634f-4543-b044-5fe20cf6d1d6
120 lines
4.4 KiB
XML
120 lines
4.4 KiB
XML
<?xml version="1.0" encoding="UTF-8" ?>
|
|
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
|
|
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
|
|
<chapter id="portstyle">
|
|
<title>Style guide</title>
|
|
<sect1>
|
|
<title>Overview</title>
|
|
<para>A port consists of a directory and its contents, within a
|
|
category subdirectory of the root of the ports tree. This document
|
|
serves as a reference for the directory structure of a single port
|
|
and the layout of the files within.</para>
|
|
|
|
<para>The only required file in a port is Portfile. The port file
|
|
should be thought of as a set of declarations rather than a piece
|
|
of code. It is best to format the port file is if it were a table
|
|
consisting of keys and values. In fact, the simplest of ports
|
|
will only contain a small block of values. Therefore, whitespace
|
|
should not be strown about haphazardly. Nicely formatted compact
|
|
tables will result in more values being visible at the same
|
|
time. </para>
|
|
|
|
<para>Try to adhere to these guidelines, but remember that this
|
|
is only a guide. No set of rules can adequately cover all cases,
|
|
and in some cases the best solution is to break the rules.</para>
|
|
|
|
</sect1>
|
|
|
|
<sect1>
|
|
<title>Specifics</title>
|
|
|
|
<sect2>
|
|
<title>Subversion ID tags</title>
|
|
<para>On the first line of the Portfile you should put a svn
|
|
ID tag. This tag will be expanded by svn when the Portfile is
|
|
committed and allows people to see at a glance details like
|
|
who was the last person to commit to a port and when the last
|
|
commit was performed.</para>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>PortSystem</title>
|
|
<para>At the top of the port file is the requirement statement.
|
|
There is a single space between the "PortSystem" statement and
|
|
the version number. </para>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Variable assignments</title>
|
|
<para>Variable assignments such as "set libver" can be
|
|
considered a single word on the left side, with a single
|
|
space between "set" and the variable name, followed by tabs to
|
|
line up with the right side. </para>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Categories</title>
|
|
<para>The first category listed for a port is the port's
|
|
primary category and should coincide with the subdirectory t
|
|
hat the port resides in. Additional categories can be listed,
|
|
but should be descriptive and accurate. </para>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Items across multiple lines</title>
|
|
<para>When items require multiple lines, they can be separated
|
|
from the previous and next items with a blank line. Indent the
|
|
additional lines to the same column that the right side begins
|
|
on in the first line. If a single statement needs to span
|
|
multiple lines, use a 2 space indentation from the first line
|
|
for all additional lines. </para>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Braces or curly brackets "{}"</title>
|
|
<para>the braces may appear on the first and last lines rather
|
|
than on their own lines. This is done because the right side of
|
|
the port file is already indented, and to make port file read
|
|
like a table. Use a single space after the brace. Indent
|
|
additional lines to this same column. </para>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Variants</title>
|
|
<para>Variants are like any other part of the port file. Space,
|
|
indent, and format them the same way other sections are
|
|
formatted. The actual variant statement, "variant" followed
|
|
by the name of the variant, can be treated as a single
|
|
statement and thus placed together on the left side and
|
|
separated by a single space. </para>
|
|
|
|
</sect2>
|
|
|
|
<sect2>
|
|
<title>Patch files</title>
|
|
<para>Patch files reside in the files/ directory in the port's
|
|
base directory. There should be one patch file for every file
|
|
that needs to be patched. It is perfectly reasonable to use
|
|
provided patches that affect multiple files, but do not
|
|
create new patches that do so. Their names should begin
|
|
with "patch-". The rest of the name should come from the
|
|
name of the file that they apply to. In many cases just the
|
|
base name of the file being patched is enough. For files
|
|
such as "Makefile" this may not be the case. In this case,
|
|
use enough components of the file's path to uniquely
|
|
distinguish the file. Separate the components with '-'
|
|
characters. The patch should apply with "patch -p0" from the
|
|
working source directory of the port. </para>
|
|
|
|
</sect2>
|
|
|
|
</sect1>
|
|
|
|
</chapter>
|