source: branches/gsoc09-logging/base/doc/portstyle.7 @ 136621

Last change on this file since 136621 was 59527, checked in by blb@…, 11 years ago

Merge from trunk (may be a few missed bits to be picked up later)

  • Property svn:eol-style set to native
  • Property svn:keywords set to Id
File size: 5.5 KB
Line 
1.\" Copyright (c) 2002 Eric Melville <eric@opendarwin.org>
2.\" All rights reserved.
3.\"
4.\" Redistribution and use in source and binary forms, with or without
5.\" modification, are permitted provided that the following conditions
6.\" are met:
7.\" 1. Redistributions of source code must retain the above copyright
8.\"    notice, this list of conditions and the following disclaimer.
9.\" 2. Redistributions in binary form must reproduce the above copyright
10.\"    notice, this list of conditions and the following disclaimer in the
11.\"    documentation and/or other materials provided with the distribution.
12.\"
13.\" THIS SOFTWARE IS PROVIDED BY Eric Melville AND CONTRIBUTORS ``AS IS'' AND
14.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
16.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
17.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
18.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
19.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
20.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
21.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
22.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
23.\" SUCH DAMAGE.
24.\"
25.Dd August 31, 2005
26.Dt PORTSTYLE 7
27.Os
28.Sh NAME
29.Nm portstyle
30.Nd style guide for ports
31.Sh DESCRIPTION
32A port consists of a directory and its contents, within a category subdirectory
33of the root of the ports tree.
34This document serves as a reference for the directory structure of a single
35port and the layout of the files within.
36.Pp
37The only required file in a port is
38.Va Portfile .
39The port file should be thought of as a set of declarations rather than a
40piece of code.
41It is best to format the port file is if it were a table consisting of keys
42and values.
43In fact, the simplest of ports will only contain a small block of values.
44Therefore, whitespace should not be strown about haphazardly.
45Nicely formatted compact tables will result in more values being visible at the
46same time.
47.Pp
48At the top of the port file is the requirement statement.
49There is a single space between the
50.Dq Li PortSystem
51statement and the version number.
52.Pp
53Use tabs to align items into columns.
54The left side should consist of single words, and will be separated from the
55more complex right side by a number of tabs that will result in all items
56begining on the same column.
57Variable assignments such as
58.Dq Li set libver
59can be considered a single word on the left side, with a single space between
60.Dq set
61and the variable name, followed by tabs to line up with the right side.
62.Pp
63The first category listed for a port is the port's primary category and should
64coincide with the subdirectory that the port resides in.
65Additional categories can be listed, but should be descriptive and accurate.
66.Pp
67Obviously a simple table of values won't do for all ports.
68More complicated ports will need to have things like multiple distribution
69files, custom targets, and variants.
70When items require multiple lines, they can be separated from the previous
71and next items with a blank line.
72Indent the additional lines to the same column that the right side begins on
73in the first line.
74Should the items require
75.Dq Li {}
76braces, the braces may appear on the first and last lines rather than on their
77own lines.
78This is done because the right side of the port file is already indented, and
79to make port file read like a table.
80Use a single space after the brace.
81Indent additional lines to this same column.
82If a single statement needs to span multiple lines, use a 2 space indentation
83from the first line for all additional lines.
84.Pp
85Variants are like any other part of the port file.
86Space, indent, and format them the same way other sections are formatted.
87The actual variant statement,
88.Dq Li variant
89followed by the name of the variant, can be treated as a single statement and
90thus placed together on the left side and separated by a single space.
91.Pp
92Sometimes it is useful to have a block of raw code for a port file.
93In these cases, either place the code at the bottom of the port file or pull it
94in from an external file, and simply format it in a well-structured manner
95with sensible indentation like any other code should be.
96.Pp
97Patch files reside in the files/ directory in the port's base directory.
98There should be one patch file for every file that needs to be patched.
99It is perfectly reasonable to use provided patches that affect multiple files,
100but do not create new patches that do so.
101Their names should begin with
102.Dq Li patch- .
103The rest of the name should come from the name of the file that they apply to.
104In many cases just the base name of the file being patched is enough.
105For files such as
106.Dq Li Makefile
107this may not be the case.
108In this case, use enough components of the file's path to uniquely distinguish
109the file.
110Separate the components with
111.Sq Li -
112characters.
113The patch should apply with
114.Dq Li patch -p0
115from the working source directory of the port.
116.Pp
117Try to adhere to these guidelines, but remember that this is only a guide.
118No set of rules can adequately cover all cases, and in some cases the best
119solution is to break the rules.
120.Sh SEE ALSO
121.Xr port 1 ,
122.Xr macports.conf 5 ,
123.Xr portfile 7 ,
124.Xr portgroup 7 ,
125.Xr porthier 7
126.Sh HISTORY
127This guide was initially written as a late addition to first release of
128MacPorts.
129.Sh AUTHORS
130.An Eric Melville Aq eric@opendarwin.org
Note: See TracBrowser for help on using the repository browser.