1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
|
.. _code_contributions:
================================================================================
Guidelines for PROJ code contributors
================================================================================
This is a guide for PROJ, casual or regular, code contributors.
Code contributions.
###############################################################################
Code contributions can be either bug fixes or new features. The process
is the same for both, so they will be discussed together in this
section.
Making Changes
~~~~~~~~~~~~~~
- Create a topic branch from where you want to base your work.
- You usually should base your topic branch off of the master branch.
- To quickly create a topic branch: ``git checkout -b my-topic-branch``
- Make commits of logical units.
- Check for unnecessary whitespace with ``git diff --check`` before
committing.
- Make sure your commit messages are in the `proper
format <http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html>`__.
- Make sure you have added the necessary tests for your changes.
- Make sure that all tests pass
Submitting Changes
~~~~~~~~~~~~~~~~~~
- Push your changes to a topic branch in your fork of the repository.
- Submit a pull request to the PROJ repository in the OSGeo
organization.
- If your pull request fixes/references an issue, include that issue
number in the pull request. For example:
::
Wiz the bang
Fixes #123.
- PROJ developers will look at your patch and take an appropriate
action.
Coding conventions
~~~~~~~~~~~~~~~~~~
Programming language
^^^^^^^^^^^^^^^^^^^^
PROJ was originally developed in ANSI C. Today PROJ is mostly developed in C++11,
with a few parts of the code base still being C. Most of the older parts of the
code base is effectively C with a few modifications so that it compiles better as
C++.
Coding style
^^^^^^^^^^^^
The parts of the code base that has started its life as C++ is formatted with
``clang-format`` using the script ``scripts/reformat_cpp.sh``. This is mostly
contained to the code in `src/iso19111/` but a few other `.cpp`-files are
covered as well.
For the rest of the code base, which has its origin in C, we don't enforce any
particular coding style, but please try to keep it as simple as possible. If
improving existing code, please try to conform with the style of the locally
surrounding code.
Whitespace
^^^^^^^^^^
Throughout the PROJ code base you will see differing whitespace use.
The general rule is to keep whitespace in whatever form it is in the
file you are currently editing. If the file has a mix of tabs and space
please convert the tabs to space in a separate commit before making any
other changes. This makes it a lot easier to see the changes in diffs
when evaluating the changed code. New files should use spaces as
whitespace.
Tools
###############################################################################
Reformatting C++ code
~~~~~~~~~~~~~~~~~~~~~~~~
The script in ``scripts/reformat_cpp.sh`` will reformat C++ code in accordance
to the project preference.
If you are writing a new ``.cpp``-file it should be added to the list in the
reformatting script.
cppcheck static analyzer
~~~~~~~~~~~~~~~~~~~~~~~~
You can run locally ``scripts/cppcheck.sh`` that is a wrapper script around the
cppcheck utility. This tool is used as part of the quality control of the code.
cppcheck can have false positives. In general, it is preferable to rework the
code a bit to make it more 'obvious' and avoid those false positives. When not
possible, you can add a comment in the code like
::
/* cppcheck-suppress duplicateBreak */
in the preceding line. Replace
duplicateBreak with the actual name of the violated rule emitted by cppcheck.
CLang Static Analyzer (CSA)
~~~~~~~~~~~~~~~~~~~~~~~~~~~
CSA is run by the ``travis/csa`` build configuration. You may also run it locally.
Preliminary step: install clang. For example:
::
wget http://releases.llvm.org/6.0.0/clang+llvm-6.0.0-x86_64-linux-gnu-ubuntu-16.04.tar.xz
tar xJf clang+llvm-6.0.0-x86_64-linux-gnu-ubuntu-16.04.tar.xz
mv clang+llvm-6.0.0-x86_64-linux-gnu-ubuntu-16.04 clang+llvm-6
Run configure under the scan-build utility of clang:
::
./clang+llvm-6/bin/scan-build ./configure
Build under scan-build:
::
./clang+llvm-6/bin/scan-build make [-j8]
If CSA finds errors, they will be emitted during the build. And in which case,
at the end of the build process, scan-build will emit a warning message
indicating errors have been found and how to display the error report. This
is with someling like
::
./clang+llvm-6/bin/scan-view /tmp/scan-build-2018-03-15-121416-17476-1
This will open a web browser with the interactive report.
CSA may also have false positives. In general, this happens when the code is
non-trivial / makes assumptions that hard to check at first sight. You will
need to add extra checks or rework it a bit to make it more "obvious" for CSA.
This will also help humans reading your code !
Typo detection and fixes
~~~~~~~~~~~~~~~~~~~~~~~~
Run ``scripts/fix_typos.sh``
Include What You Use (IWYU)
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Managing C includes is a pain. IWYU makes updating headers a bit
easier. IWYU scans the code for functions that are called and makes
sure that the headers for all those functions are present and in
sorted order. However, you cannot blindly apply IWYU to PROJ. It
does not understand ifdefs, other platforms, or the order requirements
of PROJ internal headers. So the way to use it is to run it on a copy
of the source and merge in only the changes that make sense.
Additions of standard headers should always be safe to merge. The
rest require careful evaluation. See the IWYU documentation for
motivation and details.
`IWYU docs <https://github.com/include-what-you-use/include-what-you-use/tree/master/docs>`_
|
