Changes between Version 3 and Version 4 of Guidelines/Requirements

Timestamp:

Aug 18, 2010, 10:58:23 PM (12 years ago)

Author:

Daniel James

Comment:

--

Guidelines/Requirements

@@ -1 @@
-[[PageOutline]]
+= Boost Library Requirements and Guidelines
 
-= 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
-[wiki:Guidelines/Header 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
-[wiki:Guidelines/Reuse 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 
-[wiki:Guidelines/Separate 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 [wiki:Guidelines/Test 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
-
-{{{
-#!html
-<a name="Filename_rationale_1" id="Filename_rationale_1"></a>
-}}}
-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.
-
-{{{
-#!html
-<a name="Filename_rationale_2" id="Filename_rationale_2"></a>
-}}}
-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."
-
-{{{
-#!html
-<a name="Filename_rationale_3" id="Filename_rationale_3"></a>
-}}}
-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.
-
-{{{
-#!html
-<a name="Filename_rationale_4" id="Filename_rationale_4"></a>
-}}}
-4. POSIX has special rules for names
-beginning with a period. Windows prohibits names ending in a
-period.
-
-{{{
-#!html
-<a name="Filename_rationale_5" id="Filename_rationale_5"></a>
-}}}
-5.Would be too confusing or ambiguous in certain contexts.
-
-{{{
-#!html
-<a name="Filename_rationale_6" id="Filename_rationale_6"></a>
-}}}
-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.
-
-{{{
-#!html
-<a name="Filename_rationale_7" id="Filename_rationale_7"></a>
-}}}
-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.
-
-Copyright Beman Dawes, 2003.
+This has been move back to the [http://www.boost.org/development/requirements.html main site]