Version 31 (modified by 6 years ago) ( diff ) | ,
---|
Home | Overview | Workflow | Git | GitHub | Cautions | Clone | Maintain | Patch |
Getting Started with Modular Boost
Prerequisites
- A C++ compiler installed.
- A recent release of the Git command line client installed. See Getting Started with Git for Git version requirements and information about command line clients.
If you haven't done so already, set up your git configuration:
git config --global user.name "My Name" git config --global user.email my-email@whatever.domain
A Git GUI client such as TortoiseGIT may be useful for routine work, but is not required.
Choose a protocol for cloning
The Boost super-project and libraries on GitHub support cloning via HTTPS or SSH protocols. SSH is often used by developers, but HTTPS may be required by some corporate firewalls and for read-only access. To use HTTPS instead of SSH, replace git@github.com:boostorg/boost.git
in the examples below with https://github.com/boostorg/boost.git
.
Authentication
The Boost super-project and libraries have been set up using relative URLs, so whichever protocol you use in the git clone
command will determine how subsequent access to the super-project and libraries is authenticated.
Line endings
The Boost super-project and libraries ensure correct handling of line endings regardless of platform by supplying a .gitattributes
file. However, you may also want to set git config
options for managing line endings:
On OS X, Linux, and other POSIX-like systems:
git config --global core.autocrlf input
On Windows:
git config --global core.autocrlf true
That sets the core.autocrlf
option globally, so only needs to be done once. For more on line endings, see GitHub Dealing with line endings.
Installing Modular Boost
The initial cloning will take at least 45 minutes on a 3.0 mbps Internet connection and will consume roughly 1.5 GB of disk space. Cloning is only done once, so this lengthy initial time is not a long-term concern.
From the command line on Windows:
git clone --recursive git@github.com:boostorg/boost.git modular-boost >clone.log cd modular-boost git checkout develop ||: # or whatever branch you want to use .\bootstrap .\b2 headers
On POSIX-like operating systems, with a one-time download:
git clone --recursive git@github.com:boostorg/boost.git modular-boost >clone.log cd modular-boost git checkout develop ||: # or whatever branch you want to use ./bootstrap.sh ./b2 headers
On POSIX-like operating systems, with piecemeal downloads:
git clone git@github.com:boostorg/boost.git modular-boost >clone.log # Check out only the super-project cd modular-boost git submodule update --init # Check out all the modules cd libs/accumalators
The b2 headers
step creates the boost
sub-directory hierarchy and populates it with links to the headers in the include sub-directories of the individual projects.
Experimenting
If you want to build the separately compiled Boost libraries, run the usual b2
command. For Windows:
.\b2
For POSIX-like systems:
./b2
If b2
isn't already in your path, you might want to add it now.
Testing is done just the way it has always been done. For example,
cd libs/system/test b2
should run the tests for Boost.system, all of which should pass.
Submodules
You might want to review the git submodule command at this point, since understanding how to work with submodules is critical to working with the modular Boost repositories.
Developing
Checking out a particular branch
The clone
operation above leaves each individual library in the modular-boost
local repository in a detached state that is not very useful if you want to make changes and also could result in data loss. So the first thing you want to do for a library you are going to modify is switch it to the branch you want to work on. For example, if you want to do some maintenance on the develop
branch of mylib
, do this:
cd modular-boost/libs/mylib git checkout develop git branch -vv git pull
git branch -vv
is just to reassure yourself you are tracking the remote repo. If not, you have some problem, such as a very old version git.
git pull
ensures the checkout is up to date.
You are now ready to start regular maintenance! See Getting Started with Modular Boost Library Maintenance.