source: trunk/doc/guide/xml/portfiles/style.xml @ 4478

Last change on this file since 4478 was 4478, checked in by fkr, 17 years ago

Bug:
Submitted by:
Reviewed by:
Approved by:
Obtained from:

big guide-update from wbb@. Thanks Will!

  • Property svn:eol-style set to native
File size: 4.4 KB
Line 
1<?xml version="1.0" encoding="UTF-8" ?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3                "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4<chapter id="portstyle">
5        <title>Style guide</title> 
6        <sect1>
7                <title>Overview</title> 
8                <para>A port consists of a directory and its contents, within a
9                category subdirectory of the root of the ports tree.  This document
10                serves as a reference for the directory structure of a single port
11                and the layout of the files within.</para>
12
13                <para>The only required file in a port is Portfile.  The port file
14                should be thought of as a set of declarations rather than a piece
15                of code.  It is best to format the port file is if it were a table
16                consisting of keys and values.  In fact, the simplest of ports
17                will only contain a small block of values.  Therefore, whitespace
18                should not be strown about haphazardly. Nicely formatted compact
19                tables will result in more values being visible at the same
20                time. </para>
21
22                <para>Try to adhere to these guidelines, but remember that this
23                is only a guide.  No set of rules can adequately cover all cases,
24                and in some cases the best solution is to break the rules.</para>
25
26        </sect1>
27       
28        <sect1>
29                <title>Specifics</title> 
30               
31                <sect2>
32                        <title>CVS ID tags</title> 
33                        <para>On the first line of the Portfile you should put a cvs
34                        ID tag. This tag will be expanded by cvs when the Portfile is
35                        committed and allows people to see at a glance details like
36                        who was the last person to commit to a port and when the last
37                        commit was performed.</para>
38
39                </sect2>
40
41                <sect2>
42                        <title>PortSystem</title> 
43                        <para>At the top of the port file is the requirement statement.
44                        There is a single space between the "PortSystem" statement and
45                        the version number. </para>
46
47                </sect2>
48
49                <sect2>
50                        <title>Variable assignments</title> 
51                        <para>Variable assignments such as "set libver" can be
52                        considered a single word on the left side, with a single
53                        space between "set" and the variable name, followed by tabs to
54                        line up with the right side. </para>
55
56                </sect2>
57
58                <sect2>
59                        <title>Categories</title> 
60                        <para>The first category listed for a port is the port's
61                        primary category and should coincide with the subdirectory t
62                        hat the port resides in. Additional categories can be listed,
63                        but should be descriptive and accurate. </para>
64
65                </sect2>
66
67                <sect2>
68                        <title>Items across multiple lines</title> 
69                        <para>When items require multiple lines, they can be separated
70                        from the previous and next items with a blank line. Indent the
71                        additional lines to the same column that the right side begins
72                        on in the first line. If a single statement needs to span
73                        multiple lines, use a 2 space indentation from the first line
74                        for all additional lines. </para>
75
76                </sect2>
77
78                <sect2>
79                        <title>Braces or curly brackets "{}"</title> 
80                        <para>the braces may appear on the first and last lines rather
81                        than on their own lines. This is done because the right side of
82                        the port file is already indented, and to make port file read
83                        like a table. Use a single space after the brace. Indent
84                        additional lines to this same column. </para>
85
86                </sect2>
87
88                <sect2>
89                        <title>Variants</title> 
90                        <para>Variants are like any other part of the port file. Space,
91                        indent, and format them the same way other sections are
92                        formatted. The actual variant statement, "variant" followed
93                        by the name of the variant, can be treated as a single
94                        statement and thus placed together on the left side and
95                        separated by a single space. </para>
96
97                </sect2>
98
99                <sect2>
100                        <title>Patch files</title> 
101                        <para>Patch files reside in the files/ directory in the port's
102                        base directory. There should be one patch file for every file
103                        that needs to be patched. It is perfectly reasonable to use
104                        provided patches that affect multiple files, but do not
105                        create new patches that do so. Their names should begin
106                        with "patch-". The rest of the name should come from the
107                        name of the file that they apply to. In many cases just the
108                        base name of the file being patched is enough. For files
109                        such as "Makefile" this may not be the case. In this case,
110                        use enough components of the file's path to uniquely
111                        distinguish the file. Separate the components with '-'
112                        characters. The patch should apply with "patch -p0" from the
113                        working source directory of the port. </para>
114
115                </sect2>
116
117        </sect1>
118
119</chapter>
Note: See TracBrowser for help on using the repository browser.