From 9e9491d8d9775ba481a26dca72bd42f67cad1666 Mon Sep 17 00:00:00 2001 From: Beman Dawes Date: Thu, 27 Jul 2000 14:27:00 +0000 Subject: [PATCH] Initial HTML commit [SVN r7640] --- count_bdy.htm | 1166 ++++++++++++++++++++++++++++++++++++ faq.htm | 118 ++++ feature_model_diagrams.htm | 103 ++++ formal_review_process.htm | 94 +++ header.htm | 102 ++++ imp_vars.htm | 201 +++++++ index.htm | 62 ++ lib_guide.htm | 268 +++++++++ submission_process.htm | 169 ++++++ use_other_libs.htm | 52 ++ 10 files changed, 2335 insertions(+) create mode 100644 count_bdy.htm create mode 100644 faq.htm create mode 100644 feature_model_diagrams.htm create mode 100644 formal_review_process.htm create mode 100644 header.htm create mode 100644 imp_vars.htm create mode 100644 index.htm create mode 100644 lib_guide.htm create mode 100644 submission_process.htm create mode 100644 use_other_libs.htm diff --git a/count_bdy.htm b/count_bdy.htm new file mode 100644 index 0000000..0dd6f0b --- /dev/null +++ b/count_bdy.htm @@ -0,0 +1,1166 @@ + + + + + + + Counted Body Techniques + + + + + + + + + + + + + +

Counted Body Techniques

+ + + +

Kevlin Henney
+ +(kevlin@acm.org, khenney@qatraining.com)

+ + + + + + + + +
+

And then there were none...

+ + + + + + + +
+

Attached vs detached

+ + + + + + +
+

A requirements based approach

+ + + + + + +
+

Getting smart

+ + + + + + +
+

Public accountability

+ + + + + + + +
+

Runtime mixin

+ + + + + + + +
+

Getting smarter

+ + + + + + + + +
+

Conclusion

+ + + + + + + +

+ +

First published in Overload 25, + +April 1998, ISSN 1354-3172
+ +© Copyright Kevlin Henney, 1998, 1999
+ + + + + + + diff --git a/faq.htm b/faq.htm new file mode 100644 index 0000000..3315268 --- /dev/null +++ b/faq.htm @@ -0,0 +1,118 @@ + + + + +FAQ + + + + + + + + + + + + + + + + +
c++boost.gif (8819 bytes)Home Libraries People FAQ More
+ +

Frequently Asked Questions

+ +

How is a library accepted for posting on the site? An initial review by the +library master filters out libraries which do not meet the absolute requirements (must be +C++, ownership clear, reasonable format, etc.)  The author is free to rework and +resubmit libraries which do not pass initial muster. This is encouraged, particularly when +reviewers like the idea behind a library but feel that details are lacking.

+ +

Is there any assurance libraries actually work as claimed? No. The review +process will hopefully eliminate the most seriously flawed libraries, but a well +constructed library with hidden defects is likely to slip through. Encouraging ordinary +users to report their experience with a library is intended to address such concerns.

+ +

How does someone submit a comment?  Send email to boost@egroups.com.

+ +

How does someone submit a library? See Library +Guidelines

+ +

Are commercial libraries requiring a fee acceptable? No. However, a library that +a commercial enterprise makes available without fee is acceptable. If the description of +the library makes a low-key plug for the supplier, that is acceptable as long as the +library delivers real value and isn’t just a Trojan horse for the plug.

+ +

Are shareware libraries acceptable? No. At least initially, only free libraries +will be accepted.

+ +

Are open source license libraries acceptable?  No, not currently. +Open source licenses often require redistribution or availability of source code, +inclusion of license document with machine-executable redistribution, give the initial +developer rights to licensee modifications, and need a lawyer to understand.  These +would be immediate disqualifications for many business, commercial, and consumer +applications. Boost aims to avoid subjecting users to hard-to-comply-with license terms.
+
+This is subject to review for a particularly important piece of software, or as the +industry changes.

+ +

Must full source code be provided? Yes, these are source code libraries.

+ +

What about documentation? A very simple library might be accepted with only a +well commented header file. For more substantial libraries, some form of documentation is +certainly going to be expected.  HTML is the preferred form.

+ +

Are platform specific libraries acceptable? There is a preference for portable +libraries. Libraries will be accepted that have portable interfaces but require platform +specific implementations, as long as the author supplies implementations for a couple of +disparate major operating systems.

+ +

Must a library do useful work? No. A library meant as a teaching example or +demonstration might not actually do any work.

+ +

Who owns the libraries? Presumably many authors will copyright their libraries. +Others authors may wish to place their libraries in the public domain. The Boost.org +policy is to only accept libraries with a clear copyright notice.  It is up to +potential users to decide if they find the copyright terms acceptable, and to not use +libraries with unacceptable copyrights.

+ +

What support is available for the libraries?  Try the boost@egroups.com mailing list.

+ +

Is there a relationship between Boost.org and the C++ Standards Committee? +  No. The people who started Boost.org were all on the committee, but that was just +happenstance.

+ +

Will the Boost.org libraries become part of the next C++ Standard?  Some +might, someday off in the future, but that is up to the standards committee.  To the +extent a library becomes "existing practice", the likelihood increases that +someone will propose it for future standardization. Submitting a library to Boost.org is +one way to establish existing practice - as long as enough people are interested to +download and use it!

+ +

Is the site a commercial business? No. It is just some people getting together +as a kind of cyberspace civic association. If it ever needs to incorporate, it would be as +non-profit organization.

+ +

Is there any charge for submitting libraries or reviews to Boost.org? No. Unlike +the standards committees, you don’t have to pay to volunteer!

+ +

Will the site include material beyond libraries? The main focus is on libraries, +but if people contribute occasional articles or other material to make the site more +interesting, that could be a nice fit.

+ +

How do I unzip the distribution files on my [whatever] computer? +  The .zip format is used for distribution because there are free decoders and +encoders available for many, many different platforms. See the Info-ZIP web site, which includes a FAQ and +much other useful information about the .zip format. Many commercial compressor-archiver +utilities also support this format.

+ +

-- End of FAQ --

+ +

Revised May 17, 1999

+ + diff --git a/feature_model_diagrams.htm b/feature_model_diagrams.htm new file mode 100644 index 0000000..40e807b --- /dev/null +++ b/feature_model_diagrams.htm @@ -0,0 +1,103 @@ + + + + + + +Feature Model Diagrams + + + + +

Feature Model Diagrams in text and HTML

+

By Beman Dawes

+

Introduction

+

In their seminal book, Generative Programming, Czarnecki and Eisenecker (C&E) +describe how to build feature models [C&E 4.4] consisting of a feature +diagram plus semantic, rationale, and other attributes.  Feature models are +then used to drive design cycles which eventually lead to manual or automatic +assembly of configurations.

+

Feature models provide a language to describe the library variability that is +often such an issue in boost.org discussions. The Whorf hypothesis that +"Language shapes the way we think, and determines what we can think +about" seems to apply.  In discussion of library variability issues, +we have been crippled by lack of a good language. With feature models we now +have a language to carry on the dialog.

+

The graphical feature diagrams presented by C&E are not in a suitable +form for the email discussions boost.org depends upon. The hierarchical nature +of feature diagrams can be represented by a simple text-based feature diagram +language.  A feature model can also take advantage of the hyperlinks +inherent in HTML.

+

Grammar

+

The grammar for the feature diagram language is expressed in Extended +Bakus-Naur Form; ::= represents productions, [...] represents options, {...} +represents zero or more instances, and represents | alternatives.

+
+ 
feature-model       ::= concept-name details { feature }
+ 
feature             ::= feature-name [details]
+ 
details             ::= "(" feature-list ")"      // required features
+                      | "[" feature-list "]"      // optional features
+ 
feature-list        ::= element { "|" element }   // one only
+                      | element { "+" element }   // one or more
+                      | element { "," element }   // all
+                                                  // [a+b] equivalent to [a,b]
+ 
element             ::= feature
+                      | details
+ 
concept-name        ::= name
+ 
feature-name        ::= name
+
+

The usual lexical conventions apply. Names are case-insensitive and consist +of a leading letter, followed by letters, digits, underscores or hyphens, with +no spaces allowed.

+

At least one instance of each name should be hyperlinked to the corresponding +Feature Description.

+

While the grammar is intended for written communication between people, it +may also be trivially machine parsed for use by automatic tools.

+

Feature Description

+

Descriptive information is associated with each concept or feature. According +to [C&E 4.4.2] this includes:

+ +

What is a Feature?

+

A feature [C&E 4.9.1] is "anything users or client programs might +want to control about a concept.  Thus, during feature modeling, we +document no only functional features ... but also implementation features, ..., +various optimizations, alternative implementation techniques, and so on."

+

Example

+
+ 
special-container ( organization,
+                    performance,
+                    interface  )         // all required
+ 
organization [ ordered + indexed ]       // zero or more (4 configurations)
+ 
indexed [ hash-function ]                // zero or one  (2 configurations)
+ 
performance ( fast | small | balanced )  // exactly one  (3 configurations)
+ 
interface ( STL-style + cursor-style )   // one or more  (3 configurations)
+
+

There should be feature descriptions for some-container, organization, +ordered, indexed, hash-function, performance, fast, small, balanced, interface, +STL-style, and cursor-style.

+

The number of possible configurations is  (2 + 2*2) * 3 * 3 = 54, +assuming no constraints.

+

There are equivalent representations. For example:

+
+ 
special-container ( organization[ ordered+indexed[ hash-function ]],
+                    performance( fast|small|balanced ),
+                    interface( STL-style+cursor-style ) )
+
+

References

+

Krzysztof Czarnecki and Ulrich W. Eisenecker, Generative +Programming, Addison-Wesley, 2000, ISBN 0-210-30977-7

+
+

Revised 23 July 2000

+

© Copyright Beman Dawes, 2000

+ + + + diff --git a/formal_review_process.htm b/formal_review_process.htm new file mode 100644 index 0000000..a552056 --- /dev/null +++ b/formal_review_process.htm @@ -0,0 +1,94 @@ + + + + + + +Formal Review Process + + + + + + + + + + + + + +
c++boost.gif (8819 bytes)HomeLibrariesPeopleFAQMore
+

Formal Review Process

+

The Formal Review process determines if a proposed library should be accepted +as a Boost library.

+

The final "accept" or "reject" decision is made by the +Review Manager, based on review comments received from boost mailing list +members.

+

Members only can see Formal +Review Schedule for the current review schedule. 

+

Comments

+

All Boost mailing list members are encouraged to submit Formal Review +comments:

+
+ +
+

Private comments to a library submitter may be helpful to her or him, but +won't help the Review Manager reach a decision, so the other forms are +preferred.

+

Preparing review comments

+

Comments may be brief or lengthy, but basically the Review Manager needs your +answers to several questions.  If you identify problems along the way, +please note if they are minor, serious, or showstoppers.

+ +

Results

+

At the conclusion of the comment period, the Review Manager will post a +message to the mailing list saying if the library has been accepted or +rejected.  A rationale should be provided, but its extent is up to the +Review Manager.

+

Notes for Review Managers

+

Consider writing a Review page for posting on the web site.

+

In Review pages or mailing list postings, do quote review comments if you +wish, but don't identify authors of private comments.

+

Notes for Library Authors

+

A proposed library should remain stable during the review period; it is just +going to confuse and irritate reviewers if there are numerous changes.  It +is, however, useful to upload fixes for serious bugs right away, particularly +those which prevent reviewers from fully evaluating the library.  Post a +notice of such fixes on the mailing list.

+

Library improvements suggested by reviewers should be held until after the +completion of review period. Such changes can then be incorporated in the final +submission file sent to the webmaster for posting.  If the suggested +changes might affect reviewer's judgments,  post a notice of the pending +change on the mailing list.

+
+

Revised 13 June, 2000

+

 

+ + + + diff --git a/header.htm b/header.htm new file mode 100644 index 0000000..5d65137 --- /dev/null +++ b/header.htm @@ -0,0 +1,102 @@ + + + + +Header policy + + + + + + + + + + + + + + + + +
c++boost.gif (8819 bytes)HomeLibrariesPeopleFAQMore
+

Header Policy

+

Header files are the place where a library comes into contact with user code +and other libraries.  To co-exist peacefully and productively, headers must +be "good neighbors".

+

Here are the standards for namespace boost headers.    Many of +these are also reasonable guidelines for general use. +

+

Sample Header

+
//  Boost general library furball.hpp header file  ---------------------------//
+
+//  (C) Copyright Your Name 1998. Permission to copy, use, modify, sell and
+//  distribute this software is granted provided this copyright notice appears
+//  in all copies. This software is provided "as is" without express or implied
+//  warranty, and with no claim as to its suitability for any purpose.
+
+//  $Id$ or other version information
+
+#ifndef BOOST_FURBALL_HPP
+#define BOOST_FURBALL_HPP
+
+namespace boost {
+
+//  Furball class declaration  -----------------------------------------------//
+
+  class furball
+  {
+    public: 
+      void throw_up();
+    private:
+      int whatever;
+  };  // furball
+
+} // namespace
+
+#endif  // BOOST_FURBALL_HPP
+

Coding Style

+

The alert reader will have noticed that the sample +header employs a certain coding style for indentation, positioning braces, +commenting ending braces, and similar formatting issues.  These stylistic +issues are viewed as personal preferences and are not part of the Boost Header +Policy.

+
+

Revised 23 June, 2000

+ + + + diff --git a/imp_vars.htm b/imp_vars.htm new file mode 100644 index 0000000..9d1a191 --- /dev/null +++ b/imp_vars.htm @@ -0,0 +1,201 @@ + + + + + + +Implementation Variations + + + + + + + + + + + + + +
c++boost.gif (8819 bytes)HomeLibrariesPeopleFAQMore
+

Implementation Variations

+

Separation of interface and implementation

+

The interface specifications for boost.org library components (as well as for +quality software in general) are conceptually separate from implementations of +those interfaces. This may not be obvious, particularly when a component is +implemented entirely within a header, but this separation of interface and +implementation is always assumed. From the perspective of those concerned with +software design, portability, and standardization, the interface is what is +important, while the implementation is just a detail.

+

Dietmar Kühl, one of the original boost.org contributors, comments "The +main contribution is the interface, which is augmented with an implementation, +proving that it is possible to implement the corresponding class and providing a +free implementation."

+ +

Implementation variations

+ +

There may be a need for multiple implementations of an interface, to +accommodate either platform dependencies or performance tradeoffs. Examples of +platform dependencies include compiler shortcomings, file systems, thread +mechanisms, and graphical user interfaces. The classic example of a performance +tradeoff is a fast implementation which uses a lot of memory versus a slower +implementation which uses less memory.

+

Boost libraries generally use a configuration +header, boost/config.hpp, to capture compiler and platform +dependencies.  Although the use of boost/config.hpp is not required, it is +the preferred approach for simple configuration problems.  

+

Boost policy

+

The Boost policy is to avoid platform dependent variations in interface +specifications, but supply implementations which are usable over a wide range of +platforms and applications.  That means boost libraries will use the +techniques below described as appropriate for dealing with platform +dependencies.

+

The Boost policy toward implementation variations designed to enhance +performance is to avoid them unless the benefits greatly exceed the full +costs.  The term "full costs" is intended to include both +tangible costs like extra maintenance, and intangible cost like increased +difficulty in user understanding.

+ +

Techniques for providing implementation variations

+ +

Several techniques may be used to provide implementation variations. Each is +appropriate in some situations, and not appropriate in other situations.

+

Single general purpose implementation

+

The first technique is to simply not provide implementation variation at +all.  Instead, provide a single general purpose implementation, and forgo +the increased complexity implied by all other techniques.

+

Appropriate:  When it is possible to write a single portable +implementation which has reasonable performance across a wide range of +platforms. Particularly appropriate when alternative implementations differ only +in esoteric ways.

+

Not appropriate: When implementation requires platform specific +features, or when there are multiple implementation possible with widely +differing performance characteristics.

+

Beman Dawes comments "In design discussions some implementation is often +alleged to be much faster than another, yet  a timing test discovers no +significant difference. The lesson is that while algorithmic differences may +affect speed dramatically, coding differences such as changing a class from +virtual to non-virtual members or removing a level of indirection are unlikely +to make any measurable difference unless deep in an inner loop. And even in an +inner loop, modern CPU’s often execute such competing code sequences in the +same number of clock cycles!  A single general purpose implementation is +often just fine."

+

Or as Donald Knuth said, "Premature optimization is the root of all +evil." (Computing Surveys, vol 6, #4, p 268).

+

Macros

+

While the evils of macros are well known, there remain a few cases where +macros are the preferred solution:

+
+ +
+

Appropriate:  For small compile-time variations which would +otherwise be costly or confusing to install, use, or maintain. More appropriate +to communicate within and between library components than to communicate with +library users.

+

Not appropriate:  If other techniques will do.

+

To minimize the negative aspects of macros:

+
+ +
+

Separate files

+

A library component can have multiple variations, each contained in its own +separate file or files.  The files for the most appropriate variation are +copied to the appropriate include or implementation directories at installation +time.

+

The way to provide this approach in boost libraries is to include specialized +implementations as separate files in separate sub-directories in the .ZIP +distribution file. For example, the structure within the .ZIP distribution file +for a library named foobar which has both default and specialized variations +might look something like:

+
+ 
foobar.h		// The default header file
+foobar.cpp		// The default implementation file
+readme.txt		// Readme explains when to use which files
+self_contained/foobar.h	// A variation with everything in the header
+linux/foobar.cpp      	// Implementation file to replace the default
+win32/foobar.h          // Header file to replace the default
+win32/foobar.cpp	// Implementation file to replace the default
+
+

Appropriate:  When different platforms require different +implementations, or when there are major performance differences between +possible implementations. 

+

Not appropriate:  When it makes sense to use more that one of the +variations in the same installation.

+

Separate components

+

Rather than have several implementation variations of a single component, +supply several separate components. For example, the Boost library currently +supplies scoped_ptr and shared_ptr classes rather than +a single smart_ptr class parameterized to distinguish between the +two cases.  There are several ways to make the component choice:

+
+ +
+

Appropriate: When the interfaces for the variations diverge, and when +it is reasonably to use more than one of the variations. When run-time selection +of implementation is called for.

+

Not appropriate: When the variations are data type, traits, or +specialization variations which can be better handled by making the component a +template. Also not appropriate when choice of variation is best done by some +setup or installation mechanism outside of the program itself.  Thus +usually not appropriate to cope with platform differences.

+

Note: There is a related technique where the interface is specified as +an abstract (pure virtual) base class (or an interface definition language), and +the implementation choice is passed off to some third-party, such as a +dynamic-link library or object-request broker. While that is a powerful +technique, it is way beyond the scope of this discussion.

+

Template-based approaches

+

Turning a class or function into a template is often an elegant way to cope +with variations.  Template-based approaches provide optimal space and time +efficiency in return for constraining the implementation selection to compile +time. 

+

Important template techniques include:

+
+ +
+
+ 
SomeClass<fast>  my_fast_object;  // fast and small are empty classes
+SomeClass<small> my_small_object; // used just to select specialization
+
+
+
+

Appropriate: When the need for variation is due to data type or +traits, or is performance related like selecting among several algorithms, and +when a program might reasonably use more than one of the variations.

+

Not appropriate:  When the interfaces for variations are +different, or when choice of variation is best done by some mechanism outside of +the program itself.  Thus usually not appropriate to cope with platform +differences.

+
+

Revised 23 June, 2000

+ + + + diff --git a/index.htm b/index.htm new file mode 100644 index 0000000..1c97f2d --- /dev/null +++ b/index.htm @@ -0,0 +1,62 @@ + + + + + + +More Information + + + + + + + + + + + + + +
c++boost.gif (8819 bytes)HomeLibrariesPeopleFAQMore
+

More Information

+

Boost Policies

+

These policies explain what is expected of boost libraries and the process +for library submissions.

+
+

Library Requirements and Guidelines.  + Basic standards for those preparing a submission.

+

Library Submission Process.  + How to submit a library to Boost.

+

Library Formal Review Process. + Including how to submit a review comment.

+

Header Policy.  Headers are where a + library contacts its users, so programming practices are particularly + important.

+

Implementation Variations.  + Sometimes one size fits all, sometimes it doesn't.  This page deals with + the trade-offs.

+
+

Links

+
+

The C++ Standard (ISO/IEC 14882) is available online as a PDF file from the + ANSI (American National Standards Institute) + Electronic Standards Store.  The price is $US 18.00. The document is + certainly not a tutorial, but is interesting to those who care about the + precise specification of the language and the standard library.

+
+

Articles and Papers

+
+

Counted Body Techniques by Kevlin + Henney is must reading for those interested in reference counting, a + widely used object management idiom.  Originally published in Overload + magazine.

+

Feature Model Diagrams in text and + HTML describes how to represent feature model diagrams in text form.

+
+
+

Revised 16 July, 2000

+ + + + diff --git a/lib_guide.htm b/lib_guide.htm new file mode 100644 index 0000000..260ea55 --- /dev/null +++ b/lib_guide.htm @@ -0,0 +1,268 @@ + + + + +Library Requirements and Guidelines + + + + + + + + + + + + + + + + +
c++boost.gif (8819 bytes)HomeLibrariesPeopleFAQMore
+

Boost Library Requirements and Guidelines

+

This page describes requirements and guidelines for the content +of a library submitted to Boost.

+

See the Boost Library +Submission Process page for a description of the process involved.

+

Requirements

+

To avoid the frustration and wasted time of a proposed library being +rejected, it must meets these requirements:

+ +

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

+ +

Portability requirements

+ +

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

+

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.org won't accept libraries without clear copyright information.

+

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

+ + + + + + + + + +

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.

+

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: +

+

Rationale

+

Rationale for some of the requirements and guidelines follows.

+

Exception-specification rationale

+

Exception specifications [ISO 15.4] are sometimes coded to indicate what +exceptions may be thrown, or because the programmer hopes they will improved +performance.  But consider the follow 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

+

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:

+ +
+

Source code fonts rationale

+

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.

+
+

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 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

+

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.

+
+

Revised 24 July, 2000

+ + + + diff --git a/submission_process.htm b/submission_process.htm new file mode 100644 index 0000000..63d722b --- /dev/null +++ b/submission_process.htm @@ -0,0 +1,169 @@ + + + + + + +Library Submission Process + + + + + + + + + + + + + +
c++boost.gif (8819 bytes)HomeLibrariesPeopleFAQMore
+

Boost Library Submission Process

+

This page describes the process of getting a library accepted by Boost.  +The process is still evolving, so if you have suggestions for improvement by all +means post them on the mailing list.

+

See the Boost Library Requirements and Guidelines +page for issues of content.

+

Steps for getting a library accepted by Boost:

+ +

Learn about Boost

+

Subscribe to the mailing list for a +while, or look through the archives.  +Click around the web site.  Understand the Requirements.  +Read the rest of this page to learn about the process.  Otherwise, you will +just end up wasting everyone's time.

+

There is a culture associated with Boost, aimed at encouraging high quality +libraries by a process of discussion and refinement.

+

If what you really want is a site that will just post your library without +even looking at it, you should go elsewhere.

+

Determine interest

+

Potential library submitters should use the mailing +list as a forum to gauge interest a possible submission.

+

A message might be as simple as "Is there any interest in a library +which solves Traveling Salesperson problems in linear time?"

+

A bit of further description or snippet of code may be helpful. Messages +should be plain text; not rich text, HTML, etc.

+

Please don't post lengthy descriptions, documentation, or code to the mailing +list, and no attachments, even small ones.  Please post lengthy material in +the eGroups boost Files section +(formerly called the " vault"). 

+

Preliminary submission

+

If response to an initial query indicates interest, then post preliminary +files in the Files section of +the boost eGroups web site if you haven't already done so.

+

Refinement

+

Discuss, refine, resubmit.  Repeat until satisfied.

+

The exact details of this process varies a lot.  Sometimes it is public, +on the mailing list, sometimes a lot of discussion happens in private +emails.  For some libraries the process is over quickly, for others it goes +on for months.  It's often challenging, and sometimes leads off in +completely unexpected directions.  

+

The archive of past +messages is one way to see how this process worked for other boost +libraries. 

+

Formal Review

+

[The Formal Review procedure is new as of 9 May, 2000, and will be refined +as experience dictates.]

+

Once a library author feels a submission (which presumably is now in the +files/vault) has matured enough for formal review, the author sends a message +requesting a formal review to the mailing list.  Please use a subject in +the form "Review Request: library" where library is replaced by +the library name.

+

Reviews are scheduled so that:

+ +

Before a library can be scheduled for review, an active boost member not +connected with the library submission must volunteer to be the "Review +Manager" for that library. The review manager decides on the schedule, +posts a notice when the review period starts, how long it lasts, and how boost +members can contribute their comments. The review manager collects comments, +chairs any discussions, and then when the review period is over, decides if +there is enough consensus to accept the library.

+

See Formal Review Process for +details.

+

Members only can see Formal +Review Schedule for the current library review schedule. 

+

[The plan is that the first several reviews will be managed by long-time +boost contributors who will be encouraged to experiment with the review +process.   Presumably, successful processes will evolve over time and +can then be documented.]

+

Boost site posting

+

Packaging

+

All of the files which make up the library should be combined and compressed +into a single final submission file using the .zip format.  Free encoders +and decoders for this format running on many different platforms are available +at the Info-ZIP web site, which +includes a FAQ and much other useful information about the .zip format. Many +commercial compressor-archiver utilities also support this format.

+

Final Submission file

+

The final submission file contains the material that will live on the +boost.org web site.  The closer the submission file mirrors the directory +structure and format of the web site, the easier it is for the webmaster to +integrate it into the web site. +

The submission file for a library named foo should include these +subdirectories, with the contents indicated: +

+

libs/foo +

+

boost

+ +

boost/detail

+ +
+

Transmission

+

Submit via email to webmaster@boost.org.   +Attach the .zip submission file.  In the email message, please include your +email address, postal mail address, and telephone number, if boost.org doesn't +already have them. Your addresses and phone number will not appear on the web +site (unless you include them in your biography).  Anonymous postings are +not accepted.

+

People pages

+

If the boost.org web site doesn't already have your capsule biography +and  picture (optional, with not-too-serious pictures preferred), please +send them mailto:webmaster@boost.org. It is +up to you as to whether or not the biography includes your email address or +other contact information.  The preferred picture format is .jpg, but other +common formats are acceptable.  The preferred image size is 500x375 but the +webmaster has photo editing software and can do the image preparation if +necessary.

+

Lifecycle

+

Libraries are software; they loose their value over time if not +maintained.  Details still hazy.

+
+

Revised 19 June, 2000

+ + + + diff --git a/use_other_libs.htm b/use_other_libs.htm new file mode 100644 index 0000000..2aecade --- /dev/null +++ b/use_other_libs.htm @@ -0,0 +1,52 @@ + + + + + + + +Use other Boost or C + + + + + +

(Details)

+

The benefits of using components from other libraries include clearer, more +understandable, code, reduced development and maintenance costs, and the +assurance which comes from using well-known and trusted building blocks.

+

The costs incurred may include added compilation and runtime costs, and +undesirable coupling between components.  If the interface to the +additional component is complex, using it may make code less readable, and thus +actually increase development and maintenance costs.

+

Example where another boost component should be used:  +boost::noncopyable (in boost/utility.hpp) has considerable benefits; it +simplifies code, improves readability, and signals intent.  Costs are low +as coupling is limited;  it uses no other classes and includes only the +generally lightweight headers <boost/config.hpp> and <cstddef>.   +There are no runtime costs at all. With costs so low and benefits so high, other +boost libraries should use boost::noncopyable except in exceptional +circumstances.

+

Example where a standard library component might be used: Providing +diagnostic output as a debugging aid can be a nice feature for a library. Yet +using Standard Library iostreams for the purpose involves a lot of additional +coupling, if iostreams is otherwise unused, and may be a complete waste if the +library is used in a GUI or embedded application.  It might be better to +redesign the boost library so that the user supplies the output mechanism, +avoiding marginal use of iostreams.

+

Example where another boost component should not be used:  The +boost dir_it library has considerable coupling and runtime costs, not to mention +portability issues with unsupported operating systems.  While completely +appropriate when directory iteration is required, it would not be reasonable for +another boost library to use dir_it just to check that a file is available +before opening, since Standard Library file open functionality does this at +lower cost.  Don't use dir_it just for the sake of using a boost library.

+

 

+

 

+ + + +