Changes between Initial Version and Version 1 of Guidelines/Requirements

Timestamp:

Feb 14, 2010, 11:37:10 AM (13 years ago)

Author:

Daniel James

Comment:

--

Guidelines/Requirements

@@ +1 @@
+[[PageOutline]]
+
+= Boost Library Requirements and Guidelines = #intro
+
+== Introduction == #Introduction
+
+This page describes requirements and guidelines for the
+content of a library submitted to Boost.
+
+See the
+[wiki:Guidelines/Submissions Boost Library Submission Process]
+page for a description of the process involved.
+
+== Requirements == #Requirements
+
+To avoid the frustration and wasted time of a proposed
+library being rejected, it must meets these requirements:
+
+ *  The license must meet the [#License license requirements]
+    below. Restricted licenses like the GPL and
+    LGPL are not acceptable.
+ *  The copyright [#Ownership ownership] must be
+    clear.
+ *  The library must be generally useful and not restricted
+    to a narrow problem domain.
+ *  The library must meet the [#Portability portability requirements] below.
+ *  The library must come reasonably close to meeting the
+    [#Guidelines Guidelines] below.    
+     *  [#Design_and_Programming Design and Programming]
+     *  [#Directory_structure Directory Structure]
+     *  [#Documentation Documentation]
+ *  The author must be willing to participate in discussions
+    on the mailing list, and to refine the library
+    accordingly.
+
+There's no requirement that an author read the mailing list
+for a time before making a submission. It has been noted,
+however, that submissions which begin "I just started to read
+this mailing list ..." seem to fail, often embarrassingly.
+
+=== License requirements === #License
+
+The preferred way to meet the license requirements is to use
+the [http://www.boost.org/LICENSE_1_0.txt Boost Software License]. See
+[http://www.boost.org/users/license.html license information]. If for
+any reason you do not intend to use the Boost Software License,
+please discuss the issues on the Boost
+[http://www.boost.org/community/groups.html#main developers mailing list]
+first.
+
+The license requirements:
+
+ *  Must be simple to read and understand.
+ *  Must grant permission without fee to copy, use and modify
+    the software for any use (commercial and
+    non-commercial).
+ *  Must require that the license appear on all copies of the
+    software source code.
+ *  Must not require that the license appear with executables
+    or other binary uses of the library.
+ *  Must not require that the source code be available for
+    execution or other binary uses of the library.
+ *  May restrict the use of the name and description of the
+    library to the standard version found on the Boost web
+    site.
+
+=== Portability requirements === #Portability
+
+ *  A library's interface must portable and not restricted to
+    a particular compiler or operating system.
+ *  A library's implementation must if possible be portable
+    and not restricted to a particular compiler or operating
+    system. If a portable implementation is not possible,
+    non-portable constructions are acceptable if reasonably easy
+    to port to other environments, and implementations are
+    provided for at least two popular operating systems (such as
+    UNIX and Windows).
+ *  There is no requirement that a library run on C++
+    compilers which do not conform to the ISO standard.
+ *  There is no requirement that a library run on any
+    particular C++ compiler. Boost contributors often try to
+    ensure their libraries work with popular compilers. The
+    boost/config.hpp
+    [http://www.boost.org/doc/libs/release/libs/config/config.htm configuration header]
+    is the preferred mechanism for working around
+    compiler deficiencies.
+
+Since there is no absolute way to prove portability, many
+boost submissions demonstrate practical portability by
+compiling and executing correctly with two different C++
+compilers, often under different operating systems. Otherwise
+reviewers may disbelieve that porting is in fact practical.
+
+=== Ownership === #Ownership
+
+Are you sure you own the library you are thinking of
+submitting? "How to Copyright Software" by MJ Salone, Nolo
+Press, 1990 says:
+
+  Doing work on your own time that is very similar to
+  programming you do for your employer on company time can
+  raise nasty legal problems. In this situation, it's best to
+  get a written release from your employer in advance.
+
+Place a copyright notice in all the important files you
+submit. Boost won't accept libraries without clear copyright
+information.
+
+== Guidelines == #Guidelines
+
+Please use these guidelines as a checklist for preparing the
+content a library submission. Not every guideline applies to
+every library, but a reasonable effort to comply is
+expected.
+
+=== Design and Programming === #Design_and_Programming
+
+Aim first for clarity and correctness; optimization should
+be only a secondary concern in most Boost libraries.
+
+Aim for ISO Standard C++. Than means making effective use of
+the standard features of the language, and avoiding
+non-standard compiler extensions. It also means using the C++
+Standard Library where applicable.
+
+Headers should be good neighbors. See the
+[http://www.boost.org/development/header.html header policy]. See
+[#Naming_consistency Naming consistency].
+
+Follow quality programming practices. See, for example,
+"Effective C++" 2nd Edition, and "More Effective C++", both by
+Scott Meyers, published by Addison Wesley.
+
+Use the C++ Standard Library or other Boost libraries, but
+only when the benefits outweigh the costs. Do not use libraries
+other than the C++ Standard Library or Boost. See
+[http://www.boost.org/development/reuse.html Library reuse].
+
+Read
+[http://www.boost.org/community/implementation_variations.html Implementation Variation]
+to see how to supply performance, platform, or
+other implementation variations.
+
+Read the 
+[http://www.boost.org/development/separate_compilation.html guidelines for libraries with separate source]
+ to see how to ensure that
+compiled link libraries meet user expectations.
+
+Use the naming conventions of the C++ Standard Library (See
+[#Naming Naming conventions rationale]):
+
+ *  Names (except as noted below) should be all lowercase,
+    with words separated by underscores.
+ *  Acronyms should be treated as ordinary names (e.g.
+    `xml_parser` instead of
+    `XML_parser`).
+ *  Template parameter names begin with an uppercase
+    letter.
+ *  Macro (gasp!) names all uppercase and begin with
+    `BOOST_`.
+
+Choose meaningful names - explicit is better than implicit,
+and readability counts. There is a strong preference for clear
+and descriptive names, even if lengthy.
+
+Use exceptions to report errors where appropriate, and write
+code that is safe in the face of exceptions.
+
+Avoid exception-specifications. See 
+[#Exception-specification exception-specification rationale].
+
+Provide sample programs or confidence tests so potential
+users can see how to use your library.
+
+Provide a regression test program or programs which follow
+the [http://www.boost.org/development/test.html Test Policies and Protocols].
+
+Although some boost members use proportional fonts, tabs,
+and unrestricted line lengths in their own code, boost's widely
+distributed source code should follow more conservative
+guidelines:
+
+ *  Use fixed-width fonts. See [#code_fonts fonts rationale].
+ *  Use spaces rather than tabs. See [#Tabs tabs rationale].
+ *  Limit line lengths to 80 characters.
+
+End all documentation files (HTML or otherwise) with a
+copyright message and a licensing message. See the 
+[http://www.boost.org/users/license.html license information] page for the
+preferred form.
+
+Begin all source files (including programs, headers,
+scripts, etc.) with:
+
+ *  A comment line describing the contents of the file.
+ *  Comments describing copyright and licensing: again, the
+    preferred form is indicated in the 
+    [http://www.boost.org/users/license.html license information] page
+ *  Note that developers should not provide a copy of
+    `LICENSE_1_0.txt` with their libraries: Boost
+    distributions already include a copy in the Boost root
+    directory.
+ *  A comment line referencing your library on the Boost web
+    site. For example:
+
+        // See http://www.boost.org/libs/foo for library home page.
+
+    Where `foo` is the directory name (see below)
+    for the library. As well as aiding users who come across a
+    Boost file detached from its documentation, some of Boost's
+    automatic tools depend on this comment to identify which
+    library header files belong to.
+
+Make sure your code compiles in the presence of the
+`min()` and `max()` macros. Some platform
+headers define `min()` and `max()` macros
+which cause some common C++ constructs to fail to compile. Some
+simple tricks can protect your code from inappropriate macro
+substitution:
+
+ *  If you want to call `std::min()` or
+    `std::max()`:
+     *  If you do not require argument-dependent look-up, use
+        `(std::min)(a,b)`.
+     *  If you do require argument-dependent look-up, you
+        should:
+         *  `#include <boost/config.hpp>`
+         *  Use `BOOST_USING_STD_MIN();` to bring
+            `std::min()` into the current scope.
+         *  Use `min BOOST_PREVENT_MACRO_SUBSTITUTION
+            (a,b);` to make an argument-dependent call to
+            `min(a,b)`.
+ *  If you want to call
+    `std::numeric_limits<int>::max()`, use
+    `(std::numeric_limits<int>::max)()`
+    instead.
+ *  If you want to call a `min()` or
+    `max()` member function, instead to doing
+    `obj.min()`, use `(obj.min)()`.
+ *  If you want to declare or define a function or a member
+    function named `min` or `max`, then you
+    must use the `BOOST_PREVENT_MACRO_SUBSTITUTION`
+    macro. Instead of writing `int min() { return 0;
+    }` you should write `int min
+    BOOST_PREVENT_MACRO_SUBSTITUTION () { return 0; }` This
+    is true regardless if the function is a free (namespace
+    scope) function, a member function or a static member
+    function, and it applies for the function declaration as well
+    as for the function definition.
+
+=== Directory Structure and Filenames === #Directory_structure
+
+Naming requirements ensure that file and directory names are
+relatively portable, including to ISO 9660:1999 (with
+extensions) and other relatively limited file systems.
+Superscript links are provided to detailed rationale for each
+choice.
+
+ *  Names must contain only
+    '''lowercase'''^[#Filename_rationale_1 1]^ ASCII letters
+    (`'a'`-`'z'`), numbers
+    (`'0'`-`'9'`), underscores
+    (`'_'`), hyphens (`'-'`), and periods
+    (`'.'`). Spaces are not allowed^[#Filename_rationale_2 2]^.
+ *  Directory names must not contain periods
+    (`'.'`)^[#Filename_Rationale_3 3]^.
+ *  The first and last character of a file name must not be a
+    period (`'.'`)^[#Filename_rationale_4 4]^.
+ *  The first character of names must not be a hyphen
+    (`'-'`)^[#Filename_rationale_5 5]^.
+ *  The maximum length of directory and file names is 31
+    characters^[#Filename_rationale_6 6]^.
+ *  The total path length must not exceed 207
+    characters^[#Filename_rationale_7 7]^.
+
+Other conventions ease communication:
+
+ *  Files intended to be processed by a C++ compiler as part
+    of a translation unit should have '''a three-letter
+    filename extension ending in "pp"'''. Other files
+    should ''not'' use extensions ending in "pp". This
+    convention makes it easy to identify all of the C++ source in
+    Boost.
+ *  All libraries have at their highest level a primary
+    directory named for the particular library. See 
+    [#Naming_consistency Naming consistency]. The primary
+    directory may have sub-directories.
+ *  For very simple libraries implemented entirely within the
+    library header, all files go in the primary directory (except
+    headers, which go in the boost header directory).
+
+==== Boost standard sub-directory names ==== #subdirectory
+
+||Sub-directory||Contents                                                 ||Required                ||
+||`build`      ||Library build files such as a Jamfile.                   ||If any build files.     ||
+||`doc`        ||Documentation (HTML) files.                              ||If several doc files.   ||
+||`example`    ||Sample program files.                                    ||If several sample files.||
+||`src`        ||Source files which must be compiled to build the library.||If any source files.    ||
+||`test`       ||Regression or other test programs or scripts.            ||If several test files.  ||
+
+==== Redirection ==== #Redirection
+
+The primary directory should always contain a file named
+index.html (or index.htm). Authors have requested this so that
+they can publish URL's in the form
+''http://www.boost.org/libs/lib-name'' with the assurance a
+documentation reorganization won't invalidate the URL. Boost's
+internal tools are also simplified by knowing that a library's
+documentation is always reachable via the simplified URL.
+
+If the documentation is in a doc sub-directory, the primary
+directory index.html file should just do an automatic
+redirection to the doc subdirectory:
+{{{
+#!html
+<pre>
+&lt;!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"&gt;
+
+&lt;html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"&gt;
+&lt;head&gt;
+  &lt;title&gt;Boost.<var>Name</var> Documentation&lt;/title&gt;
+  &lt;meta http-equiv="Content-Type" content="text/html; charset=us-ascii" /&gt;
+  &lt;meta http-equiv="refresh" content="0; URL=doc/index.html" /&gt;
+&lt;/head&gt;
+
+&lt;body&gt;
+  Automatic redirection failed, please go to &lt;a href=
+  "doc/index.html"&gt;doc/index.html&lt;/a&gt;
+&lt;/body&gt;
+&lt;/html&gt;
+</pre>
+}}}
+
+=== Naming consistency === #Naming_consistency
+
+As library developers and users have gained experience with
+Boost, the following consistent naming approach has come to be
+viewed as very helpful, particularly for larger libraries that
+need their own header subdirectories and namespaces.
+
+Here is how it works. The library is given a name that
+describes the contents of the library. Cryptic abbreviations
+are strongly discouraged. Following the practice of the C++
+Standard Library, names are usually singular rather than
+plural. For example, a library dealing with file systems might
+chose the name "filesystem", but not "filesystems", "fs" or
+"nicecode".
+
+ *  The library's primary directory (in parent
+    ''boost-root/libs'') is given that same name. For
+    example, ''boost-root/libs/filesystem''.
+ *  The library's primary header directory (in parent
+    ''boost-root/boost'') is given that same name. For
+    example, ''boost-root/boost/filesystem''.
+ *  The library's primary namespace (in parent
+    ''::boost'') is given that same name, except when
+    there's a component with that name (e.g.,
+    ''boost::tuple''), in which case the namespace name is
+    pluralized. For example, ''::boost::filesystem''.
+
+When documenting Boost libraries, follow these conventions
+(see also the following section of this document):
+
+ *  The library name is set in roman type.
+ *  The library name is capitalized.
+ *  A period between "Boost" and the library name (e.g.,
+    Boost.Bind) is used if and only if the library name is not
+    followed by the word "library".
+ *  The word "library" is not part of the library name and is
+    therefore lowercased.
+
+Here are a few examples of how to apply these
+conventions:
+
+ *  Boost.Bind was written by Peter Dimov.
+ *  The Boost Bind library was written by Peter Dimov.
+ *  I regularly use Bind, a Boost library written by Peter Dimov.
+
+=== Documentation === #Documentation
+
+Even the simplest library needs some documentation; the
+amount should be proportional to the need. The documentation
+should assume the readers have a basic knowledge of C++, but
+are not necessarily experts.
+
+The format for documentation should be HTML, and should not
+require an advanced browser or server-side extensions. Style
+sheets are acceptable. ECMAScript/JavaScript is not acceptable.
+The documentation entry point should always be a file named
+index.html or index.htm; see [#Redirection Redirection].
+
+There is no single right way to do documentation. HTML
+documentation is often organized quite differently from
+traditional printed documents. Task-oriented styles differ from
+reference oriented styles. In the end, it comes down to the
+question: Is the documentation sufficient for the mythical
+"average" C++ programmer to use the library successfully?
+
+Appropriate topics for documentation often include:
+
+ *  General introduction to the library. The introduction
+    particularly needs to include:
+     *  A very high-level overview of what the library is
+        good for, and perhaps what it isn't good for,
+        understandable even by those with no prior knowledge of
+        the problem domain.
+     *  The simplest possible ("hello world") example of
+        using the library.
+ *  Tutorial covering basic use cases.
+ *  Reference documentation:
+     *  Description of each class.
+     *  Relationship between classes.
+     *  For each function, as applicable, description,
+        requirements (preconditions), effects, post-conditions,
+        returns, and throws.
+     *  Discussion of error detection and recovery
+        strategy.
+ *  How to compile and link.
+ *  How to test.
+ *  Version or revision history.
+ *  Rationale for design decisions. See [#Rationale Rationale rationale].
+ *  Acknowledgements. See [#Acknowledgements Acknowledgments rationale.]
+
+If you need more help with how to write documentation you
+can check out the article on 
+[http://www.boost.org/doc/libs/release/more/writingdoc/index.html Writing Documentation for Boost].
+
+== Rationale == #Rationale
+
+Rationale for some of the requirements and guidelines
+follows.
+
+=== Exception-specification rationale === #Exception-specification
+
+Exception specifications [ISO 15.4] are sometimes coded to
+indicate what exceptions may be thrown, or because the
+programmer hopes they will improve performance. But consider
+the following member from a smart pointer:
+{{{
+T& operator*() const throw()  { return *ptr; }
+}}}
+
+This function calls no other functions; it only manipulates
+fundamental data types like pointers Therefore, no runtime
+behavior of the exception-specification can ever be invoked.
+The function is completely exposed to the compiler; indeed it
+is declared inline Therefore, a smart compiler can easily
+deduce that the functions are incapable of throwing exceptions,
+and make the same optimizations it would have made based on the
+empty exception-specification. A "dumb" compiler, however, may
+make all kinds of pessimizations.
+
+For example, some compilers turn off inlining if there is an
+exception-specification. Some compilers add try/catch blocks.
+Such pessimizations can be a performance disaster which makes
+the code unusable in practical applications.
+
+Although initially appealing, an exception-specification
+tends to have consequences that require '''very'''
+careful thought to understand. The biggest problem with
+exception-specifications is that programmers use them as though
+they have the effect the programmer would like, instead of the
+effect they actually have.
+
+A non-inline function is the one place a "throws nothing"
+exception-specification may have some benefit with some
+compilers.
+
+=== Naming conventions rationale === #Naming
+
+The C++ standard committee's Library Working Group discussed
+this issue in detail, and over a long period of time. The
+discussion was repeated again in early boost postings. A short
+summary:
+
+ *  Naming conventions are contentious, and although several
+    are widely used, no one style predominates.
+ *  Given the intent to propose portions of boost for the
+    next revision of the C++ standard library, boost decided to
+    follow the standard library's conventions.
+ *  Once a library settles on a particular convention, a vast
+    majority of stakeholders want that style to be consistently
+    used.
+
+=== Source code fonts rationale === #code_fonts
+
+Dave Abrahams comments: An important purpose (I daresay the
+primary purpose) of source code is communication: the
+documentation of intent. This is a doubly important goal for
+boost, I think. Using a fixed-width font allows us to
+communicate with more people, in more ways (diagrams are
+possible) right there in the source. Code written for
+fixed-width fonts using spaces will read reasonably well when
+viewed with a variable-width font, and as far as I can tell
+every editor supporting variable-width fonts also supports
+fixed width. I don't think the converse is true.
+
+=== Tabs rationale === #Tabs
+
+Tabs are banned because of the practical problems caused by
+tabs in multi-developer projects like Boost, rather than any
+dislike in principle. See [http://www.boost.org/community/groups.html#archive mailing list archives].
+Problems include maintenance of a single source file by
+programmers using tabs and programmers using spaces, and the
+difficulty of enforcing a consistent tab policy other than just
+"no tabs". Discussions concluded that Boost files should either
+all use tabs, or all use spaces, and thus the decision to stick
+with spaces.
+
+=== Directory and File Names rationale === #FileNamesRat
+
+ 1. Some legacy file systems require
+    single-case names. Single-case names eliminate casing mistakes
+    when moving from case-insensitive to case-sensitive file
+    systems.
+
+ 2. This is the lowercase portion of
+    the POSIX portable filename character set. To quote the POSIX
+    standard, "Filenames should be constructed from the portable
+    filename character set because the use of other characters can
+    be confusing or ambiguous in certain contexts."
+
+ 3. Strict implementations of ISO
+    9660:1999 and some legacy operating systems prohibit dots in
+    directory names. The need for this restriction is fading, and
+    it will probably be removed fairly soon.
+
+ 4. POSIX has special rules for names
+    beginning with a period. Windows prohibits names ending in a
+    period.
+
+ 5. Would be too confusing or ambiguous in certain contexts.
+
+ 6. We had to draw the line
+    somewhere, and so the limit imposed by a now obsolete Apple
+    file system was chosen years ago. It still seems a reasonable
+    limit to aid human comprehension.
+
+ 7. ISO 9660:1999.
+
+=== ECMAScript/JavaScript rationale === #JavaScript
+
+Before the 1.29.0 release, two Boost libraries added
+ECMAScript/JavaScript documentation. Controversy followed (see
+[http://www.boost.org/community/groups.html#archive mailing list archives]),
+and the developers were asked to remove the
+ECMAScript/JavaScript. Reasons given for banning included:
+
+ *  Incompatible with some older browsers and some text based
+    browsers.
+ *  Makes printing docs pages difficult.
+ *  Often results in really bad user interface design.
+ *  "It's just annoying in general."
+ *  Would require Boost to test web pages for
+    ECMAScript/JavaScript compliance.
+ *  Makes docs maintenance by other than the original
+    developer more difficult.
+
+=== Rationale rationale === #Rationale_rationale
+
+Rationale is defined as "The fundamental reasons for
+something; basis" by the American Heritage Dictionary.
+
+Beman Dawes comments: Failure to supply contemporaneous
+rationale for design decisions is a major defect in many
+software projects. Lack of accurate rationale causes issues to
+be revisited endlessly, causes maintenance bugs when a
+maintainer changes something without realizing it was done a
+certain way for some purpose, and shortens the useful lifetime
+of software.
+
+Rationale is fairly easy to provide at the time decisions
+are made, but very hard to accurately recover even a short time
+later.
+
+=== Acknowledgements rationale === #Acknowledgements
+
+As a library matures, it almost always accumulates
+improvements suggested to the authors by other boost members.
+It is a part of the culture of boost.org to acknowledge such
+contributions, identifying the person making the suggestion.
+Major contributions are usually acknowledged in the
+documentation, while minor fixes are often mentioned in
+comments within the code itself.