v3 flag enabled
Log In
Log In

Contributors Frequently Asked Questions

News

Contributors Frequently Asked Questions

This section contains answers to the common questions that new contributors to Boost often have.

Topics

Adding New Libraries

  1. Do Boost libraries typically come from gauging outside interest, or perhaps more from developers following their own interests?

    Most Boost Libraries originate from individual developers, or small teams, following their own interests, rather than from organized external demand. Typically, self-motivated developers identify a gap in the C++ ecosystem or have a strong interest in a particular domain. To be clear, Boost is not driven by corporate feature requests, community polling or public wishlists, nor top-down direction (though The C++ Alliance might sponsor, or partially sponsor, work it deems of specific value, such as it did with https://www.boost.org/libs/json">Boost.Json). The community acts as a gatekeeper to ensure quality, generality, and long-term usefulness, rather than as a source for library concepts.

  2. If there is social media discussion on new libraries, typically what does the discussion entail?

    The new libraries most requested tend to be more like updates to existing libraries. There’s a common desire for more comprehensive asynchronous programming support, often for higher-level abstractions or more extensive async features. Another example is more programming options, say for an enhanced version of https://www.boost.org/libs/program_options">Boost.ProgramOptions, or for libraries supporting earlier or later C++ standards, such as requests to support pre-C++17 standards.

Boost Software License

  1. Where can I read the current version of the Boost Software License?

    Here: https://www.boost.org/doc/user-guide/bsl.html">The Boost Software License.

  2. How should Boost programmers apply the license to source and header files?

    Add a multi-line comment based on the following template, substituting appropriate text for the name and date on the top line:

    cpp // Copyright Joe Coder 2004 - 2006. // Distributed under the Boost Software License, Version 1.0. // (See accompanying file LICENSE_1_0.txt or copy at // https://www.boost.org/LICENSE_1_0.txt)

    Notes

    1. Leave an empty line before and after the above comment block.

    2. It is fine if the copyright and license messages are not on different lines; in no case should there be other intervening text.

  3. How should the license be applied to documentation files rather than source files?

    Similarly to the way it is applied to source files: the user should see the very same text indicated in the template above, with the only difference that your local copy of LICENSE_1_0.txt should also be linked to.

  4. How should Boost programmers maintain the copyright messages?

    Copyright is only claimed for changes meeting a certain threshold of originality. Therefore, the copyright message only covers expressions of creativity. It is up to authors of changes to add themselves to the copyright message if they so decide. Typically, a new claimant is added when someone takes over maintenance of a library or a new version of an existing library is developed. In principle, do not remove previous copyright claims - just add new claims and/or claimants.

  5. How is the Boost Software License (BSL) different from the GNU General Public License (GPL)?

    The https://opensource.org/license/gpl-3-0">GNU General Public License is longer, and may be harder to understand. The Boost license permits the creation of derivative works for any use with no legal requirement to release your source code. Other differences include BSL not requiring reproduction of copyright messages for object code redistribution, and the fact that BSL is not "viral": if you distribute your own code along with some Boost code, the BSL applies only to the Boost code (and modified versions thereof); you are free to license your own code under any terms you like.

  6. Do I have to copyright/license trivial files?

    Yes, even a test file that just contains an empty main() should have a copyright notice. Files without copyright notices make corporate lawyers nervous, and that’s a barrier to adoption. The more Boost is uniformly copyrighted and licensed, the better.

  7. Can I use the Boost Software License for my own projects outside of Boost?

    Yes, there are no restrictions on the use of the license itself.

  8. Is the Boost license Open Source?

    Yes. The https://opensource.org/">Open Source Initiative certified the https://opensource.org/license/bsl-1-0">Boost Software License 1.0 in early 2008.

Development Environments

  1. Many developers opt for lightweight integrated developer environments (IDEs), rather than the full-fledged IDE. What lightweight IDEs are popular for C++ development?

    There are several popular options for both Windows and Linux. https://www.jetbrains.com/clion/">CLion, developed by JetBrains, is a cross-platform IDE that offers advanced code analysis, refactoring tools, and integration with the CMake build system, which is commonly used in C++ projects.

    https://www.gnu.org/software/emacs/">GNU Emacs and https://www.vim.org/">Vim are highly configurable and popular among developers who prefer a more minimalistic environment. They offer powerful features for editing code, and many plugins are available to enhance development workflows.

    https://www.qt.io/product/development-tools">Qt Creator provides features like code completion, syntax highlighting, and debugging support for C++ and Qt (projects that use the Qt framework).

    https://www.sublimetext.com/index2">Sublime Text is a lightweight yet powerful text editor known for its speed and simplicity. It offers features like syntax highlighting, multiple selections, and a wide range of plugins for enhancing functionality, including support for C++ development.

    https://atom-editor.cc/">Atom is an open-source text editor developed by GitHub. It’s highly customizable and extensible through packages, and provides features like syntax highlighting, auto-completion, and project navigation.

    There are many other tools, Microsoft’s https://visualstudio.microsoft.com/">Visual Studio provides a full IDE and is well respected as a professional development environment, and https://code.visualstudio.com/Download">Visual Studio Code is a lighter weight but versatile code editor that can be extended and customized with various extensions.

Documentation

  1. What is a good overall structure for library documentation?

    Consider the following as a guide to the headings and structure of good API documentation:

    • Introduction - a compelling set of paragraphs that draw developers in by mentioning use cases, what is unique about your library, and a mention of performance and storage. Sell your library to developers here, this section is all that many developers will ever read.

    • Requirements - a section mentioning the operating systems, C++ versions, Boost library versions, compilers, hardware, and anything else that is a requirement to use your library. This is a good place to mention dependencies too, and a link to the license that the library falls under.

    • Acknowledgements - make sure to credit anyone or any organization that has helped you get this up and running.

      For more detailed information, refer to https://www.boost.org/doc/contributor-guide/docs/layout.html">Documentation Guidelines.

  2. What is the best way to document a library function, say one that takes a few parameters and returns a value?

    Your reference entry should contain all the following information:

    Title: foobar - the name of the function and nothing more.

    Intro: An introductory sentence explaining the purpose of foobar.

    Syntax: A format description of the syntax of the call.

    Parameters: A table, or bulleted list, of all the input parameters, including their name, type, and description. The description should certainly include any edge case uses of the parameter (such as providing NULL or zero perhaps to initiate a slight variation on the purpose of the function).

    Return Value: The returned value, including its type and any nuances that might occur.

    Errors and Exceptions: A list of the errors and/or exceptions that can be thrown by the function. It might not be possible to list them all if your function calls other functions, but you should certainly list all those that your library explicitly throws or returns.

    Remarks: A fuller description of the function. For simple calls this may be empty, but for an involved call go into all the nitty-gritty here.

    Example: Great to have example code shown here, or a link to an example elsewhere in your documentation that shows the function withing working code.

    See Also: If a function has alternatives or opposites, then it is helpful to link to them. If the function is a member of a class, add a link to the reference entry for the class.

Existing Boost Libraries

  1. What are the biggest pain points that developers are running into, that are not addressed by current Boost libraries?

    Some Boost libraries have a steep learning curve, especially for newcomers to C++. Simplifying the API design, providing extensive documentation, and offering beginner-friendly tutorials helps lower the barrier to entry and make your library more accessible to a wider audience.

  2. For reference, what libraries are good examples of ones that are easy to learn?

    One library known for its relatively straightforward API and ease of learning compared to some others is https://www.boost.org/libs/filesystem">Boost.Filesystem. This library provides portable facilities to work with files and directories, offering an intuitive interface for common file system operations such as file creation, deletion, copying, moving, and directory traversal. Its design is user-friendly and follows familiar patterns. https://www.boost.org/libs/filesystem">Boost.Filesystem documentation is comprehensive and well-structured. Overall, https://www.boost.org/libs/filesystem">Boost.Filesystem is often recommended as a starting point for those looking to dip their toes into Boost libraries due to its simplicity, practicality, and broad applicability across various projects.

    Other libraries that are known for their shallow learning curve include https://www.boost.org/libs/optional">Boost.Optional which is particularly useful for handling functions that may return an optional value or dealing with nullable data types in a safe and clear manner. https://www.boost.org/libs/any">Boost.Any allows developers to store objects of different types in a single container and retrieve them without typecasting. https://www.boost.org/libs/type_index">Boost.TypeIndex provides facilities for obtaining type information at runtime, making it easy to work with types dynamically.

  3. What libraries have the steepest learning curve?

  4. What libraries were the most ambitious in what they attempted to achieve?

    The many notable examples include:

    • https://www.boost.org/libs/graph">Boost.Graph provides a generic and efficient framework for working with graphs, making it suitable for a variety of applications in areas such as network analysis, optimization, and data visualization.

    • https://www.boost.org/libs/compute">Boost.Compute provides abstractions for memory management, kernel execution, and data parallelism, enabling developers to harness the computational power of modern hardware for tasks such as numerical simulations, image processing, and machine learning.

    • https://www.boost.org/libs/spirit">Boost.Spirit is ambitious in its goal of providing a high-level and composable framework for parsing complex data formats and domain-specific languages entirely within C++ code, without the need for external tools or preprocessors.

    • https://www.boost.org/libs/hana">Boost.Hana aims to simplify and modernize metaprogramming in C++, making it more accessible and powerful for developing generic libraries and applications.

  5. What libraries were the least ambitious technically?

    The useful utilities such as https://www.boost.org/libs/any">Boost.Any, https://www.boost.org/libs/variant">Boost.Variant, and https://www.boost.org/libs/optional">Boost.Optional offer relatively simple functionality. Another simpler library is https://www.boost.org/libs/bimap">Boost.Bimap which provides a container for maintaining one-to-one mappings between keys and values. While bidirectional maps are a useful data structure, the functionality provided is relatively straightforward and focused on this specific use case.

Generative Artificial Intelligence

  1. I have always been interested in Artificial Intelligence (AI), and would like to contribute an AI component library to Boost. Within the field of Generative AI, what components would work well as a C++ library?

    Of course, text and images are not the only complex constructs you might want to work with. There are too many others to list, but high-value constructs include audio and speech (breaking them down into phonemes, spectral features, or waveforms), video (decomposing into frames, objects, motion vectors, or scene segments), and time series data such as sensor data or stock prices (breaking down into patterns, cycles, and perhaps anomalies). More esoteric examples would include molecular structures and chemical compounds, social graph data, handwriting and gesture data, 3D models, and so on.

    A new Boost library could address one or more of the tasks involved in decomposing existing structures into atomic components, then the processes involved in rebuilding these components into something new that adheres to a significant set of rules/patterns/behavior. Handling user-input to guide the process is another challenging component.

    Perhaps take inspiration from the following table:

    <col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;">

    Construct

    Subcomponents / Atomic Units

    Notes

    Text

    Subwords, Characters, Tokens, Words

    BPE (Byte Pair Encoding), WordPiece, SentencePiece, or character-based tokenization

    Images

    Pixels, Patches, Segments, Regions, Object Masks

    Vision Transformers often use image patches; segmentation maps are used for context

    Audio

    Frames, Spectrogram Windows, Mel-Frequency Cepstral Coefficients (MFCCs), Waveform Samples

    Typically converted into spectrograms or embeddings for processing. MFCCs determine how humans perceive sound.

    Speech

    Phonemes, Syllables, Graphemes, Acoustic Frames

    Combines audio processing and linguistic modeling

    Video

    Frames, Clips, Objects per Frame, Motion Vectors, Scene Changes

    Often handled as sequences of images with temporal dependencies

    Time Series

    Time Steps, Sliding Windows, Seasonal Components, Trends

    Used in forecasting models like Long-Short Term Memory (LSTMs), Transformers, etc.

    3D Models

    Mesh Vertices, Faces, Point Clouds, Voxels, Primitives

    Decomposed for neural rendering or reconstruction

    Code

    Tokens, AST Nodes, Lines, Statements, Functions

    Abstract Syntax Trees (ASTs) used by code Large Language Models (LLMs)

    Music

    Notes, Chords, Bars, Timing Events, MIDI Tokens

    Representation varies: symbolic (MIDI), waveform, or spectrogram

    Sensor Data

    Events, Packets, Timestamps, Multimodal Vectors

    Used in robotics and IoT, often real-time

    text boost-token-stream/ ├── include/ │ └── boost/ │ └── token-stream/ │ ├── bpe.hpp # Public API │ ├── vocab.hpp # Vocab structure │ ├── merge_rules.hpp # Merge rules structure │ └── error.hpp # Error handling and outcome types ├── src/ │ └── bpe.cpp # Implementation (if not header-only) ├── test/ │ ├── test_bpe.cpp # Unit tests │ └── test_vocab.cpp # Vocab loading/lookup tests ├── CMakeLists.txt └── README.md

  2. I want to experiment with creating a library for scene based generative AI, but I find all the necessary components somewhat daunting. Are there Boost libraries that can lighten the load?

    For an experimental project, consider structuring it around the following, assuming the input is a raw still image, and the output is a generated image:

  3. What is considered to be best practices when testing a generative AI model, given we can never be sure when it has got it all right?

    Testing a generative AI model, or library component, is fundamentally different from traditional software testing because there’s no single correct output — outputs are often subjective, diverse, and probabilistic. However, there are best practices that help ensure quality, safety, and usefulness. Start by engaging the following methods:

    <col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;"><col style="min-width: 25px;">

    Method

    Description

    Pros

    Cons

    Automated Metrics

    BLEU, ROUGE, METEOR, Perplexity, FID (for images), etc.

    Fast, repeatable

    Poor at capturing nuance

    Human Evaluation

    Judges rate quality, relevance, etc.

    High-quality insights

    Time-consuming, subjective

    Adversarial Testing

    Try to break the model with edge cases or trick inputs

    Uncovers weaknesses

    Requires creativity and care

    Behavioral Unit Tests

    Small, targeted tests for expected responses

    Precise

    Limited coverage

    Perfect doesn’t apply in generative AI. Instead, strive for consistent quality, clear boundaries, and safe behavior:

    • Define clear evaluation goals and test across diverse datasets

    • Simulate misuse - prompt injection, toxic output, sensitive topics

    • Track hallucinations - the AI term for clearly incorrect statements or images

    • Track consistency - does the model contradict itself

    • Conduct temperature sweeps - AI term for measuring the balance between boring/repetitive and overly chaotic output

    • Be transparent and document limitations

    • Consider continuous monitoring in production - collect and analyze feedback

      A prospective generative AI Boost library would only need testing within its own domain of functionality, but the design should be cognizant of the testing a finished application is going to require.

Modular Boost

  1. What is meant by "Modular Boost"?

    Technically, Modular Boost consists of the Boost super-project and separate projects for each individual library in Boost. In terms of Git, the Boost super-project treats the individual libraries as submodules. Currently (early 2024) when the Boost libraries are downloaded and installed, the build organization does not match the modular arrangement of the Git super-project. This is largely a legacy issue, and there are advantages to the build layout matching the super-project layout. This concept, and the effort behind it, is now known as "Modular Boost".

    In the past, the term has been used more broadly to refer simply to libraries in different repositories. This definition has now been tightened to mean a flat layout where each library is in its own sub-module, and there are no sub-libraries as there have been in the past (for example, the numeric libraries).

    Refer to https://www.boost.org/doc/contributor-guide/superproject/overview.html">Super-Project Layout for a full description of the super-project.

  2. What exactly is a "modular arrangement"?

    It’s when the libraries can be used, and hence built, without creating the monolithic headers, without needing the root build files, and without needing the libraries to be arranged in the usual root/libs/<name> format.

  3. Will the move to Modular Boost change testing?

    No, unless you want to. You will still be able to test with the current non-modular way. But you could also test the modular way.

  4. How will modular Boost work if there is no root/libs/<name> structure? Or is the structure still required?

    The structure is still required for things like testing and documentation building.

  5. What happens to the numeric libraries that are currently sub-libraries, when sub-libraries are no longer supported?

    The numeric libraries have been divided into four packages: libboost-numeric-conversion/, libboost-numeric-interval/, libboost-numeric-odeint/, libboost-numeric-ublas/.

Post-Release Engagement

  1. Through what channels do Boost library authors typically receive the most feedback?

    Primarily the https://lists.boost.org/mailman/listinfo.cgi/boost-users">Boost Users Mailing List and the https://lists.boost.org/mailman/listinfo.cgi/boost">Boost Developers Mailing List. In addition, checkout GitHub Issues and Pull Requests. Also, the Boost forums on https://slack.com/">Slack can be active.

    Example of communication flow:

    1. A new library release is announced on the Boost mailing lists.

    2. Users start discussing the new release on the mailing lists, reporting initial impressions and any issues encountered.

    3. Users report bugs and request features on the relevant GitHub repository, leading to active discussions in the issues and pull requests sections.

    4. Boost library authors and contributors discuss technical details and implementation strategies on the https://lists.boost.org/mailman/listinfo.cgi/boost">Boost Developers Mailing List.

    5. Users seeking immediate help might turn to https://slack.com/">Slack or sometimes https://discord.com/">Discord for quick responses, or directly communicate with the authors if email or forum addresses are made public.

Next Post

  • Testing
    Blog

Related Posts