| 6 | | |
| 7 | | |
| 8 | | = Getting Started with Modular Boost = |
| 9 | | [[PageOutline]] |
| 10 | | |
| 11 | | == Prerequisites == |
| 12 | | |
| 13 | | * A C++ compiler installed. |
| 14 | | * A recent release of the Git command line client installed. See [wiki:Git/GitHome Getting Started with Git] for Git version requirements and information about command line clients. |
| 15 | | |
| 16 | | If you haven't done so already, set up your git configuration: |
| 17 | | |
| 18 | | {{{ |
| 19 | | git config --global user.name "My Name" |
| 20 | | git config --global user.email my-email@whatever.domain |
| 21 | | }}} |
| 22 | | |
| 23 | | A Git GUI client such as [http://code.google.com/p/tortoisegit/ TortoiseGIT] may be useful for routine work, but is not required. |
| 24 | | |
| 25 | | == Choose a protocol for cloning == |
| 26 | | |
| 27 | | The [https://github.com/boostorg/boost 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}}}. |
| 28 | | |
| 29 | | === Authentication === |
| 30 | | |
| 31 | | 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. |
| 32 | | |
| 33 | | == Line endings == |
| 34 | | |
| 35 | | 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: |
| 36 | | |
| 37 | | On OS X, Linux, and other POSIX-like systems: |
| 38 | | |
| 39 | | {{{ |
| 40 | | git config --global core.autocrlf input |
| 41 | | }}} |
| 42 | | |
| 43 | | On Windows: |
| 44 | | |
| 45 | | {{{ |
| 46 | | git config --global core.autocrlf true |
| 47 | | }}} |
| 48 | | |
| 49 | | That sets the {{{core.autocrlf}}} option globally, so only needs to be done once. For more on line endings, see [https://help.github.com/articles/dealing-with-line-endings GitHub Dealing with line endings]. |
| 50 | | |
| 51 | | == Installing Modular Boost == |
| 52 | | |
| 53 | | 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. |
| 54 | | |
| 55 | | From the command line on Windows: |
| 56 | | |
| 57 | | {{{ |
| 58 | | git clone --recursive git@github.com:boostorg/boost.git modular-boost >clone.log |
| 59 | | cd modular-boost |
| 60 | | git checkout develop ||: # or whatever branch you want to use |
| 61 | | .\bootstrap |
| 62 | | .\b2 headers |
| 63 | | }}} |
| 64 | | |
| 65 | | On POSIX-like operating systems, with a one-time download: |
| 66 | | |
| 67 | | {{{ |
| 68 | | git clone --recursive git@github.com:boostorg/boost.git modular-boost >clone.log |
| 69 | | cd modular-boost |
| 70 | | git checkout develop ||: # or whatever branch you want to use |
| 71 | | ./bootstrap.sh |
| 72 | | ./b2 headers |
| 73 | | }}} |
| 74 | | |
| 75 | | On POSIX-like operating systems, with piecemeal downloads: |
| 76 | | |
| 77 | | {{{ |
| 78 | | git clone git@github.com:boostorg/boost.git modular-boost >clone.log # Check out only the super-project |
| 79 | | cd modular-boost |
| 80 | | git submodule update --init # Check out all the modules |
| 81 | | cd libs/accumalators |
| 82 | | }}} |
| 83 | | |
| 84 | | 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. |
| 85 | | |
| 86 | | == Experimenting == |
| 87 | | |
| 88 | | If you want to build the separately compiled Boost libraries, run the usual {{{b2}}} command. For Windows: |
| 89 | | |
| 90 | | {{{ |
| 91 | | .\b2 |
| 92 | | }}} |
| 93 | | |
| 94 | | For POSIX-like systems: |
| 95 | | |
| 96 | | {{{ |
| 97 | | ./b2 |
| 98 | | }}} |
| 99 | | |
| 100 | | If {{{b2}}} isn't already in your path, you might want to add it now. |
| 101 | | |
| 102 | | Testing is done just the way it has always been done. For example, |
| 103 | | |
| 104 | | {{{ |
| 105 | | cd libs/system/test |
| 106 | | b2 |
| 107 | | }}} |
| 108 | | |
| 109 | | should run the tests for Boost.system, all of which should pass. |
| 110 | | |
| 111 | | == Submodules == |
| 112 | | |
| 113 | | You might want to review the [http://git-scm.com/docs/git-submodule git submodule command] at this point, since understanding how to work with submodules is critical to working with the modular Boost repositories. |
| 114 | | |
| 115 | | == Developing == |
| 116 | | |
| 117 | | === Checking out a particular branch === |
| 118 | | |
| 119 | | 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: |
| 120 | | |
| 121 | | {{{ |
| 122 | | cd modular-boost/libs/mylib |
| 123 | | git checkout develop |
| 124 | | git branch -vv |
| 125 | | git pull |
| 126 | | }}} |
| 127 | | |
| 128 | | {{{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. |
| 129 | | |
| 130 | | {{{git pull}}} ensures the checkout is up to date. |
| 131 | | |
| 132 | | You are now ready to start regular maintenance! See [https://svn.boost.org/trac/boost/wiki/StartModMaint Getting Started with Modular Boost Library Maintenance]. |
| 133 | | |
