Repair ReST link format
[ryppl:doc.git] / source / gettingstarted.rst
1
2 .. highlight:: git_shell
3
4 .. _getting_started:
5
6 Getting started
7 ---------------
8
9 Boost is organized in Git as a “superproject” containing `submodules
10 <http://progit.org/book/ch6-6.html>`_, each of which corresponds to an
11 individual Boost library.  A **submodule** is a *reference* to a
12 commit in an *independent* Git repository.  The submodule is used by
13 Git to clone the independent repository below the superproject's root
14 directory, and check out the referenced commit.
15
16 Clone the Boost superproject
17 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
18
19 ::
20
21   git clone git://gitorious.org/ryppl/boost.git boost-ryppl
22
23 This will clone the rypplized boost *superproject* and place the
24 result in the top-level workspace directory ``boost-ryppl/``.  Have a look at
25 the contents.  Most of boost is there, but:
26
27 * In ``boost-ryppl/`` there is a file ``.gitmodules`` that maps local
28   directories to remote git repositories::
29
30     [submodule "src/accumulators"]
31         path = src/accumulators
32         url = git://gitorious.org/boost/accumulators.git
33     [submodule "src/algorithm"]
34         path = src/algorithm
35         url = git://gitorious.org/boost/algorithm.git
36     etc
37     
38 * Under ``src`` there is an empty subdirectory for each boost library
39
40 * The command ``git submodule status`` gives the commits at which each
41   submodule should be cloned:
42
43 .. parsed-literal::
44
45     % git submodule status
46     -10ac085df521b4b294afa074e296252fabd1735b src/accumulators
47     -08578dcec8e5be7365e83107cae6f9240e215ed3 src/algorithm
48     -d037b2069c9cce96f019b02a631a51a47970bc02 src/any
49     -795ab423fecb41dba2e4e6a8be6ee8089d78136b src/array
50     *etc…*
51
52 Initialize and update the submodules
53 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
54
55 Issue the command ``git submodule init --update``:
56
57 .. parsed-literal::
58
59   % git submodule init
60   Submodule 'src/accumulators' (git://gitorious.org/boost/accumulators.git) registered for path 'src/accumulators'
61   Submodule 'src/algorithm' (git://gitorious.org/boost/algorithm.git) registered for path 'src/algorithm'
62   Submodule 'src/any' (git://gitorious.org/boost/any.git) registered for path 'src/any'
63   Submodule 'src/array' (git://gitorious.org/boost/array.git) registered for path 'src/array'
64
65   *etc…*
66
67   Initialized empty Git repository in /tmp/boost/cmake/.git/
68   remote: Counting objects: 263, done.
69
70   *etc…*
71   
72 There will be alot of output...  Git has checked out each submodule to
73 its corresponding directory inside the superproject, and.
74
75 .. “that” above makes the sentence grammatically confusing.
76
77 Now notice that the git submodule status now *has* changed::
78
79   % git submodule status
80   6dce83c277d48644fac187799876799eb66c97a2 cmake (heads/master)
81   0628a7a2d999bbbd62fd9877922c057f5f056114 src/accumulators (remotes/origin/1.41.0)
82   5cec8044c5408fadee71110194027b0e99b44721 src/algorithm (remotes/origin/1.41.0)
83   d58030ef644dc992db31fc2bd6fe3a985468eb4b src/any (remotes/origin/1.41.0)
84   
85 The minus sign to the left of the hash has disappeared, and a branch
86 (in parenthesis) has appeared on the right.
87
88 Also, the submodule directories now contain code::
89
90   % ls src/regex
91   CMakeLists.txt        example/        module.cmake    src/
92   build/                include/        performance/    test/
93   doc/          index.html      README.txt      tools/
94
95 Now you have a Boost workspace nearly ready to build.
96
97 Run cmake and generate forwarding headers
98 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
99
100 Create a build directory outside your source tree and run CMake there.
101 This step inspects your system configuration, finding installed
102 libraries, tools, etc., and generates appropriate makefiles for Boost:
103
104 .. parsed-literal::
105
106   % mkdir ../build-ryppl
107   % cd ../build-ryppl
108   % cmake ../boost-ryppl
109   -- The C compiler identification is GNU
110   -- The CXX compiler identification is GNU
111
112   *[ etc ]*
113
114   -- 
115   -- Reading boost project directories (per BUILD_PROJECTS) 
116   -- 
117   -- + preprocessor
118   -- + concept_check
119
120   *[ etc… note that 'chrono', 'process', etc appear in this list ]*
121
122   -- + wave
123   -- 
124   -- BUILD_TESTS is NONE: skipping test directories. 
125   -- 
126   -- 
127   -- BUILD_TOOLS is NONE: skipping tools. 
128   -- 
129   -- Configuring done
130   -- Generating done
131   -- Build files have been written to: *absolute-path-to-..*/build-ryppl
132
133 The last step is to generate forwarding headers.  This technique is
134 borrowed from the smart guys at Trolltech ``Qt`` toolkit.  Make the
135 target **genheaders**:
136
137 .. You need to explain where these headers go and what they do.
138
139 .. parsed-literal::
140
141   % make genheaders
142   Scanning dependencies of target genheaders
143   Generating central header directory
144   Projects located under     :  *absolute-path-to-..*/boost-ryppl
145   Fwding headers generated in:  *absolute-path-to-..*/build-ryppl/include
146
147                 serialization:  178
148                     smart_ptr:  59
149                  accumulators:  81
150
151                      *[etc etc]*
152
153                    scope_exit:  1
154                           mpl:  1041
155                        assign:  16
156   Built target genheaders
157
158
159 Now you'll notice that a  directory ``build-ryppl/include``
160 exists and is full of headers::
161
162   % ls include/boost
163   accumulators/                 multi_array/
164   algorithm/                    multi_array.hpp
165   aligned_storage.hpp           multi_index/
166
167   [etc]
168
169   memory_order.hpp              wave/
170   mpi/                          wave.hpp
171   mpi.hpp                       weak_ptr.hpp
172   mpl/                          xpressive/
173
174 And that each file simply forwards to the project from whence it
175 came::
176
177   % cat ../include/boost/wave.hpp 
178   #include "../../src/wave/include/boost/wave.hpp"
179
180 Build
181 ^^^^^
182
183 Now you can build.  To find the names of all available targets, make
184 the `help` target:
185
186 .. parsed-literal::
187
188   % make help
189   The following are some of the valid targets for this Makefile:
190   ... all (the default if no target is provided)
191   ... clean
192   ... depend
193   ... edit_cache
194   ... genheaders
195   ... install
196   ... install/local
197   ... install/strip
198   ... list_install_components
199   ... rebuild_cache
200   ... test
201   ... boost_date_time
202   ... boost_date_time-mt-shared
203   ... boost_date_time-mt-shared-debug
204   ... boost_date_time-mt-static
205   ... boost_date_time-mt-static-debug
206   ... boost_thread
207   *etc*
208
209   % make boost_date_time
210   [  0%] Built target boost_date_time-mt-static-debug
211   [  0%] Built target boost_date_time-mt-shared-debug
212   [  0%] Built target boost_date_time-mt-shared
213   [100%] Built target boost_date_time-mt-static
214   [100%] Built target boost_date_time
215     
216
217 .. How do I test my library?