]>
Commit | Line | Data |
---|---|---|
f67539c2 | 1 | // Copyright 2019-2020 Rene Rivera |
92f5a8d4 TL |
2 | // Copyright 2003, 2006 Vladimir Prus |
3 | // Distributed under the Boost Software License, Version 1.0. | |
4 | // (See accompanying file LICENSE.txt or http://www.boost.org/LICENSE_1_0.txt) | |
5 | ||
6 | = B2 contributor guidelines | |
7 | ||
8 | B2 is an open-source project. This means that we welcome and appreciate | |
9 | all contributions -- be it ideas, bug reports, or patches. This document | |
10 | contains guidelines which helps to assure that development goes on smoothly, and | |
11 | changes are made quickly. | |
12 | ||
13 | The guidelines are not mandatory, and you can decide for yourself which one to | |
14 | follow. But note, that 10 mins that you spare writing a comment, for example, | |
15 | might lead to significantly longer delay for everyone. | |
16 | ||
17 | Before contributing, make sure you are subscribed to our mailing list | |
18 | at boost-build@lists.boost.org. | |
19 | ||
20 | == Additional resources include | |
21 | ||
22 | === The issue tracker | |
23 | ||
24 | https://github.com/boostorg/build/issues | |
25 | ||
26 | === Mailing list | |
27 | ||
28 | boost-build@lists.boost.org | |
29 | ||
30 | http://lists.boost.org/boost-build/ | |
31 | ||
32 | == BUGS and PATCHES | |
33 | ||
34 | Both bugs and patches can be submitted to the GitHub tracker. | |
35 | ||
36 | When reporting a bug, please try to provide the following information: | |
37 | ||
38 | * What you did. | |
39 | * A minimal reproducible test case is very much appreciated. | |
40 | * Shell script with some annotations is much better than verbose | |
41 | description of the problem. | |
42 | * A regression test is the best (see test/test_system.html). | |
43 | ||
44 | * What you got. | |
45 | ||
46 | * What you expected. | |
47 | ||
48 | * What version of B2 did you use. If possible, please try to test with the | |
49 | develop branch state. | |
50 | ||
51 | When submitting a patch, please: | |
52 | ||
53 | * Make a single patch for a single logical change | |
54 | * Follow the policies and coding conventions below | |
55 | * Send patches as pull requests to the develop branch | |
56 | * Provide a good PR message together with the patch | |
57 | ||
58 | The purpose of message serves to communicate what was changed, and *why*. | |
59 | Without a good message, you might spend a lot of time later, wondering where | |
60 | a strange piece of code came from and why it was necessary. | |
61 | ||
62 | The good message mentions each changed file and each rule/method, saying | |
63 | what happened to it, and why. Consider, the following log message | |
64 | ||
65 | ---- | |
66 | Better direct request handling. | |
67 | ||
68 | * new/build-request.jam | |
69 | (directly-requested-properties-adjuster): Redo. | |
70 | ||
71 | * new/targets.jam | |
72 | (main-target.generate-really): Adjust properties here. | |
73 | ||
74 | * new/virtual-target.jam | |
75 | (register-actual-name): New rule. | |
76 | (virtual-target.actualize-no-scanner): Call the above, to detected bugs, | |
77 | where two virtual target correspond to one Jam target name. | |
78 | ---- | |
79 | ||
80 | The messages for the last two files are good. They tell what was changed. | |
81 | The change to the first file is clearly under-commented. | |
82 | ||
83 | It's okay to use terse messages for uninteresting changes, like ones induced | |
84 | by interface changes elsewhere. | |
85 | ||
86 | == POLICIES | |
87 | ||
88 | === Testing | |
89 | ||
90 | All serious changes must be tested. New rules must be tested by the module where | |
91 | they are declared. The test system (link:test/test_system.html[test/test_system.html]) | |
92 | should be used to verify user-observable behavior. | |
93 | ||
94 | === Documentation | |
95 | ||
96 | It turns out that it's hard to have too much comments, but it's easy to have too | |
97 | little. Please prepend each rule with a comment saying what the rule does and | |
98 | what arguments mean. Stop for a minute and consider if the comment makes sense | |
99 | for anybody else, and completely describes what the rules does. Generic phrases | |
100 | like "adjusts properties" are really not enough. | |
101 | ||
102 | When applicable, make changes to the user documentation as well. | |
103 | ||
104 | == CODING CONVENTIONS | |
105 | ||
106 | 1. All names of rules and variables are lowercase with "-" to separate | |
107 | words. | |
108 | + | |
109 | ---- | |
110 | rule call-me-ishmael ( ) ... | |
111 | ---- | |
112 | ||
113 | 2. Names with dots in them are "intended globals". Ordinary globals use a | |
114 | dot prefix: | |
115 | + | |
116 | ---- | |
117 | .foobar | |
118 | $(.foobar) | |
119 | ---- | |
120 | ||
121 | 3. Pseudofunctions or associations are <parameter>.<property>: | |
122 | + | |
123 | ---- | |
124 | $(argument).name = hello ; | |
125 | $($(argument).name) | |
126 | ---- | |
127 | ||
128 | 4. Class attribute names are prefixed with "self.": | |
129 | + | |
130 | ---- | |
131 | self.x | |
132 | $(self.x) | |
133 | ---- | |
134 | ||
135 | 5. Builtin rules are called via their ALL_UPPERCASE_NAMES: | |
136 | + | |
137 | ---- | |
138 | DEPENDS $(target) : $(sources) ; | |
139 | ---- | |
140 | ||
141 | 6. Opening and closing braces go on separate lines: | |
142 | + | |
143 | ---- | |
144 | if $(a) | |
145 | { | |
146 | # | |
147 | } | |
148 | else | |
149 | { | |
150 | # | |
151 | } | |
152 | ---- | |
f67539c2 TL |
153 | |
154 | == ENGINE | |
155 | ||
156 | Developing in the `b2` engine, the C++ part, requires two steps to be | |
157 | effective: building the "stable" engine, and developing the | |
158 | "in-progress" engine. | |
159 | ||
160 | What is the "stable" engine is up to you. It only refers to a build of the | |
161 | engine you know is at a good working state. When you are at a point the | |
162 | source is stable you can run `bootstrap.sh/bat` from the root. That will | |
163 | create the `b2` executable at the root. You can then use this version to run | |
164 | regular B2 builds as needed both within the B2 tree and in other projects. | |
165 | ||
166 | The "in-progress" engine is whatever build you happen to be testing at the | |
167 | moment. There are two ways to build this be engine. You can either | |
168 | (a) run `b2 b2` at the root, or (b) run `build.sh/bat` in `src/engine`. | |
169 | ||
170 | Using (a) will place, by default, a fully debuggable `b2` in the `.build` | |
171 | directories. You can run that one from a debugger with full symbols and | |
172 | stepping features. This should be the first choice in developing in the | |
173 | engine. | |
174 | ||
175 | After using (a) to implement functionality you can use (b) to fully test | |
176 | that functionality. The engine built from (b) is fully optimized and | |
177 | is the one used, by default, by the test system when running in the `test` | |
178 | directory. Before submitting patches it's required to build this way and | |
179 | run the tests in at least one toolset version (but preferably at least two). |