index.rst (8507B)
1 .. _mozilla_projects_nss_nss_developer_tutorial: 2 3 NSS Developer Tutorial 4 ====================== 5 6 .. _nss_coding_style: 7 8 `NSS Coding Style <#nss_coding_style>`__ 9 ---------------------------------------- 10 11 `Formatting <#formatting>`__ 12 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 13 14 .. container:: 15 16 **Line length** should not exceed 80 characters. 17 18 **Indentation level** is 4. 19 20 **Tabs** are used heavily in many NSS source files. Try to stay consistent when you modify 21 existing code. The proper use of tabs has often been confusing for new NSS developers, so in 22 ``nss/lib/ssl``, we're gradually removing the use of tabs. 23 24 **Curly braces**: both of the following styles are allowed: 25 26 .. code:: 27 28 if (condition) { 29 action1(); 30 } else { 31 action2(); 32 } 33 34 Or: 35 36 .. code:: 37 38 if (condition) 39 { 40 action1(); 41 } 42 else 43 { 44 action2(); 45 } 46 47 The former style is more common. When modifying existing code, try to stay consistent. In new 48 code, prefer the former style, as it conserves vertical space. 49 50 When a block of code consists of a single statement, NSS doesn’t require curly braces, so both of 51 these examples are fine: 52 53 .. code:: 54 55 if (condition) { 56 action(); 57 } 58 59 Or: 60 61 .. code:: 62 63 if (condition) 64 action(); 65 66 although the use of curly braces is more common. 67 68 **Multiple-line comments** should be formatted as follows: 69 70 .. code:: 71 72 /* 73 * Line1 74 * Line2 75 */ 76 77 or 78 79 .. code:: 80 81 /* 82 ** Line 1 83 ** Line 2 84 */ 85 86 The following styles are also common, because they conserve vertical space: 87 88 .. code:: 89 90 /* Line1 91 * Line2 92 */ 93 94 or 95 96 .. code:: 97 98 /* Line1 99 ** Line2 100 */ 101 102 or 103 104 .. code:: 105 106 /* Line1 107 * Line2 */ 108 109 `Naming <#naming>`__ 110 ~~~~~~~~~~~~~~~~~~~~ 111 112 .. container:: 113 114 Public functions are named ``FOO_DoOneAction``. 115 116 Global, but unexported functions, are usually named ``foo_DoOneAction``. 117 118 Variable, and function parameter names, always start with a lowercase letter. The most common 119 style is ``fooBarBaz``, although ``foobarbaz`` and ``foo_bar_baz`` are also used. 120 121 `Miscellaneous <#miscellaneous>`__ 122 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 123 124 .. container:: 125 126 **goto** can be used, to simplify resource deallocation, before returning from a function. 127 128 A data buffer is usually represented as: 129 130 .. code:: c 131 132 unsigned char *data; 133 unsigned int len; 134 135 The buffer pointer is ``unsigned char *``, as opposed to ``void *``, so we can perform pointer 136 arithmetic without casting. Use ``char *`` only if the data is interpreted as text characters. 137 138 For historical reasons, the buffer length is ``unsigned int``, as opposed to ``size_t``. 139 Unfortunately, this can be a source of integer overflow bugs on 64-bit systems. 140 141 .. _c_features: 142 143 `C Features <#c_features>`__ 144 ---------------------------- 145 146 .. container:: 147 148 NSS requires C99. However, not all features from C99 are equally available. 149 150 - Variables can be declared, at the point they are first used. 151 - The ``inline`` keyword can be used. 152 - Variadic macro arguments are permitted, but their use should be limited to using 153 ``__VA_ARGS__``. 154 - The exact-width integer types in NSPR should be used, in preference to those declared in 155 ``<stdint.h>`` (which will be used by NSPR in the future). 156 - Universal character names are not permitted, as are wide character types (``char16_t`` and 157 ``char32_t``). NSS source should only include ASCII text. Escape non-printing characters 158 (with ``\x`` if there is no special escape such as \\r, \\n, and \\t) and avoid defining 159 string literals that use non-ASCII characters. 160 - One line comments starting with ``//`` are permitted. 161 162 Check with nss-dev@ before using a language feature not already used, if you are uncertain. 163 Please update this list if you do. 164 165 These restrictions are different for C++ unit tests, which can use most C++11 features. The 166 `Mozilla C++ language features 167 guide <https://developer.mozilla.org/en-US/docs/Using_CXX_in_Mozilla_code>`__, and the `Chromium 168 C++ usage guide <https://chromium-cpp.appspot.com/>`__, list C++ features that are known to be 169 widely available and compatible. You should limit features to those that appear in both guides. 170 Ask on nss-dev@ if you think this is restrictive, or if you wish to prohibit a specific feature. 171 172 .. _nss_c_abi_backward_compatibility: 173 174 `NSS C ABI backward compatibility <#nss_c_abi_backward_compatibility>`__ 175 ------------------------------------------------------------------------ 176 177 `Functions <#functions>`__ 178 ~~~~~~~~~~~~~~~~~~~~~~~~~~ 179 180 .. container:: 181 182 Exported functions cannot be removed. 183 184 The function prototype of an exported function, cannot be changed, with these exceptions: 185 186 - A ``Foo *`` parameter can be changed to ``const Foo *``. This change is always safe. 187 188 - Sometimes an ``int`` parameter can be changed to ``unsigned int``, or an ``int *`` parameter 189 can be changed to ``unsigned int *``. Whether such a change is safe needs to be reviewed on a 190 case-by-case basis. 191 192 `Types <#types>`__ 193 ------------------ 194 195 `Structs <#structs>`__ 196 ~~~~~~~~~~~~~~~~~~~~~~ 197 198 .. container:: 199 200 Members of an exported struct, cannot be reordered or removed. 201 202 Under certain circumstances, it is safe to add new members to an exported struct at the end. 203 204 Opaque structs give us complete freedom to change them, but require applications to call NSS 205 functions, to allocate and free them. 206 207 `Enums <#enums>`__ 208 ~~~~~~~~~~~~~~~~~~ 209 210 .. container:: 211 212 The numeric values of public enumerators cannot be changed. To stress this fact, we often 213 explicitly assign numeric values to enumerators, rather than relying on the values assigned by 214 the compiler. 215 216 .. _symbol_export_lists: 217 218 `Symbol export lists <#symbol_export_lists>`__ 219 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 220 221 .. container:: 222 223 The ``manifest.mn`` file, in a directory in the NSS source tree, specifies which headers are 224 public, and which headers are private. 225 226 Public headers are in the ``EXPORTS`` variable. 227 228 Private headers,which may be included by files in other directories, are in the 229 ``PRIVATE_EXPORTS`` variable. 230 231 Private headers, that are only included by files in the same directory, are not listed in either 232 variable. 233 234 Only functions listed in the symbol export lists (``nss.def``, ``ssl.def``, ``smime.def``, etc.) 235 are truly public functions. Unfortunately, public headers may declare private functions, for 236 historical reasons. The symbol export lists are the authoritative source of public functions. 237 238 .. _behavioral_changes: 239 240 `Behavioral changes <#behavioral_changes>`__ 241 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 242 243 .. container:: 244 245 **Bug/quirk compatible**: Occasionally we cannot fix a bug, because applications may depend on 246 the buggy behavior. We would need to add a new function to provide the desired behavior. 247 248 Similarly, **new options** often need to be disabled by default. 249 250 .. _nss_reviewfeature_approval_process: 251 252 `NSS review/feature approval process <#nss_reviewfeature_approval_process>`__ 253 ----------------------------------------------------------------------------- 254 255 .. container:: 256 257 NSS doesn’t have 'super reviewers'. We wish to increase the number of NSS developers, who have 258 broad understanding of NSS. 259 260 One review is usually enough for the review to pass. For critical code reviews, such as a patch 261 release of a stable branch, two reviews may be more reasonable. 262 263 For new features, especially those that appear controversial, try to find a reviewer from a 264 different company or organization than your own, to avoid any perceptions of bias. 265 266 .. _update_nss_in_mozilla-inbound_and_mozilla-central: 267 268 `Update NSS in mozilla-inbound and mozilla-central <#update_nss_in_mozilla-inbound_and_mozilla-central>`__ 269 ---------------------------------------------------------------------------------------------------------- 270 271 .. container:: 272 273 The procedure is documented at 274 `https://developer.mozilla.org//en-US/docs/Mozilla/Developer_guide/Build_Instructions/Updating_NSPR_or_NSS_in_mozilla-central <https://developer.mozilla.org/en-US/docs/Mozilla/Developer_guide/Build_Instructions/Updating_NSPR_or_NSS_in_mozilla-central>`__. 275 276 If it is necessary to apply private patches, please document them in 277 ``<tree>/security/patches/README``.