More editorial
[ryppl:doc.git] / source / gettingstarted.rst
1 .. highlight:: git_shell
2
3 .. _getting_started:
4
5 Getting started
6 ---------------
7
8 Boost is organized in Git as a “superproject” containing `submodules
9 <http://progit.org/book/ch6-6.html>`_, each of which corresponds to an
10 individual Boost library.  A **submodule** is a *reference* to a
11 commit in an *independent* Git repository.  The submodule is used by
12 Git to clone the independent repository below the superproject's root
13 directory, and check out the referenced commit.
14
15 Clone the Boost superproject
16 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
17
18 ::
19
20   git clone git://gitorious.org/ryppl/boost.git src
21
22 This will clone the rypplized boost *superproject* and place the
23 result in the top-level workspace directory ``src/``.  Have a look at
24 the contents.  Most of boost is there, but:
25
26 .. Using “src” here doesn't feel right; too generic.  Maybe “boost-src?”
27
28 * There is no toplevel ``boost`` directory, where one normally finds
29   boosts' header files.
30
31 * There is a toplevel directory ``include``... but it is empty.
32
33 * Under ``libs``, all subdirectories are empty.
34
35 * In the ``src`` there is a file ``.gitmodules`` that maps local
36   directories to remote git repositories::
37
38     [submodule "libs/accumulators"]
39         path = libs/accumulators
40         url = git://gitorious.org/boost/accumulators.git
41     [submodule "libs/algorithm"]
42         path = libs/algorithm
43         url = git://gitorious.org/boost/algorithm.git
44     etc
45     
46 * The command ``git submodule status`` gives the commits at which each
47   submodule should be cloned:
48
49 .. parsed-literal::
50
51     % git submodule status
52     -10ac085df521b4b294afa074e296252fabd1735b libs/accumulators
53     -08578dcec8e5be7365e83107cae6f9240e215ed3 libs/algorithm
54     -d037b2069c9cce96f019b02a631a51a47970bc02 libs/any
55     -795ab423fecb41dba2e4e6a8be6ee8089d78136b libs/array
56     *etc…*
57
58 Initialize and update the submodules
59 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
60
61 Issue the command ``git submodule init``::
62
63   % git submodule init
64   Submodule 'libs/accumulators' (git://gitorious.org/boost/accumulators.git) registered for path 'libs/accumulators'
65   Submodule 'libs/algorithm' (git://gitorious.org/boost/algorithm.git) registered for path 'libs/algorithm'
66   Submodule 'libs/any' (git://gitorious.org/boost/any.git) registered for path 'libs/any'
67   Submodule 'libs/array' (git://gitorious.org/boost/array.git) registered for path 'libs/array'
68   [etc]  
69
70 Notice at this point that the *submodule status* has not changed.Now
71 update the submodules::
72
73 .. Why does the reader care that the submodule status hasn't changed?
74 .. I don't think we want to be teaching Git in this document, do you?
75 .. Why don't we just do “git submodule update --init”?
76
77   % git submodule update
78   Initialized empty Git repository in /tmp/boost/cmake/.git/
79   remote: Counting objects: 263, done.
80   [etc]
81   
82 There will be alot of output...  a git checkout of each submodule has
83 been done to its corresponding directory inside the superproject, and
84 that the checkout has been done at a specific commit.
85
86 .. “that” above makes the sentence grammatically confusing.
87
88 Now notice that the git submodule status now *has* changed::
89
90   % git submodule status
91   6dce83c277d48644fac187799876799eb66c97a2 cmake (heads/master)
92   0628a7a2d999bbbd62fd9877922c057f5f056114 src/accumulators (remotes/origin/1.41.0)
93   5cec8044c5408fadee71110194027b0e99b44721 src/algorithm (remotes/origin/1.41.0)
94   d58030ef644dc992db31fc2bd6fe3a985468eb4b src/any (remotes/origin/1.41.0)
95   
96 The minus sign to the left of the hash has disappeared, and a branch
97 (in parenthesis) has appeared on the right.
98
99 Also, the submodule directories now contain code::
100
101   % ls libs/process
102   CMakeLists.txt  build/  example/  index.htm  test/
103   README.txt      doc/    include/  source/
104   
105 Now you have a Boost workspace nearly ready to build.
106
107 .. Used to say “ryppl workspace.”  I think that's confusing, implying
108 .. this procedure is more generic than it actually is.  A project with
109 .. no ryppl dependencies might not need any submodules, for example.
110
111 Run cmake and generate forwarding headers
112 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
113
114 Generate makefiles with *cmake* in the standard way.  
115 .. I think we should say “configure with cmake” instead.  This does
116 .. more than simply generating makefiles, right?
117 I like to make a
118 subdirectory ``build/`` of my workspace and run cmake in there, so
119 that I can always tell which build corresponds to which workspace.
120 .. That is confusingly phrased: 1. The reader has no concept of why
121 .. there might be multiple workspaces 2. What happens if I run cmake
122 .. without the subdirectory?  Don't I still get build results
123 .. associated with the workspace?  This path has already been added to
124 ``.gitignore``, so all those new buildfiles won't look to git like
125 they need to be added to the project:
126
127 .. parsed-literal::
128
129   % mkdir build
130   % cd build
131   % cmake ..
132   -- The C compiler identification is GNU
133   -- The CXX compiler identification is GNU
134
135   *[ etc ]*
136
137   -- 
138   -- Reading boost project directories (per BUILD_PROJECTS) 
139   -- 
140   -- + preprocessor
141   -- + concept_check
142
143   *[ etc… note that 'chrono', 'process', etc appear in this list ]*
144
145   -- + wave
146   -- 
147   -- BUILD_TESTS is NONE: skipping test directories. 
148   -- 
149   -- 
150   -- BUILD_TOOLS is NONE: skipping tools. 
151   -- 
152   -- Configuring done
153   -- Generating done
154   -- Build files have been written to: /tmp/src/build
155
156 The last step is to generate forwarding headers.  This technique is
157 borrowed from the smart guys at Trolltech ``Qt`` toolkit.  Make the
158 target **genheaders**:
159
160 .. You need to explain where these headers go and what they do.
161
162 .. parsed-literal::
163
164   % make genheaders
165   Scanning dependencies of target genheaders
166   Generating central header directory
167   Projects located under     :  /tmp/src/libs
168   Fwding headers generated in:  /tmp/src/include
169
170                 serialization:  178
171                     smart_ptr:  59
172                  accumulators:  81
173
174                      *[etc etc]*
175
176                    scope_exit:  1
177                           mpl:  1041
178                        assign:  16
179   Built target genheaders
180
181 Now you'll notice that a superproject directory ``include/boost``
182 exists and is full of headers::
183
184   % ls ../include/boost
185   accumulators/                 multi_array/
186   algorithm/                    multi_array.hpp
187   aligned_storage.hpp           multi_index/
188
189   [etc]
190
191   memory_order.hpp              wave/
192   mpi/                          wave.hpp
193   mpi.hpp                       weak_ptr.hpp
194   mpl/                          xpressive/
195
196 And that each file simply forwards to the project from whence it
197 came::
198
199   % cat ../include/boost/wave.hpp 
200   #include "../../libs/wave/include/boost/wave.hpp"
201
202 Note also that the presence of generated files in ``build/`` and
203 ``include/`` don't worry git::
204
205   % git status
206   # On branch master
207   nothing to commit (working directory clean)
208
209 Thanks to the file ``.gitignore``.
210
211 Build
212 ^^^^^
213
214 Now you can build::
215
216   % make boost_system
217   Scanning dependencies of target boost_system-mt-static-debug
218   Building CXX object src/system/src/CMakeFiles/boost_system-mt-static-debug.dir/error_code.cpp.o
219   Linking CXX static library ../../../lib/libboost_system-mt-d.a
220   Built target boost_system-mt-static-debug
221   
222
223 .. How do I test my library?