Skip to content
Newer
Older
100644 231 lines (147 sloc) 7.52 KB
5d69a52 Houston, we have a trunk.
jcorgan authored
1 # -*- Outline -*-
2 #
78c121b Doc cleanup
jcorgan authored
3 # Copyright 2004,2007,2008,2009 Free Software Foundation, Inc.
f919f9d @trondeau Removed whitespace and added dtools/bin/remove-whitespace as a tool t…
trondeau authored
4 #
5d69a52 Houston, we have a trunk.
jcorgan authored
5 # This file is part of GNU Radio
f919f9d @trondeau Removed whitespace and added dtools/bin/remove-whitespace as a tool t…
trondeau authored
6 #
5d69a52 Houston, we have a trunk.
jcorgan authored
7 # GNU Radio is free software; you can redistribute it and/or modify
8 # it under the terms of the GNU General Public License as published by
937b719 Updated license from GPL version 2 or later to GPL version 3 or later.
eb authored
9 # the Free Software Foundation; either version 3, or (at your option)
5d69a52 Houston, we have a trunk.
jcorgan authored
10 # any later version.
f919f9d @trondeau Removed whitespace and added dtools/bin/remove-whitespace as a tool t…
trondeau authored
11 #
5d69a52 Houston, we have a trunk.
jcorgan authored
12 # GNU Radio is distributed in the hope that it will be useful,
13 # but WITHOUT ANY WARRANTY; without even the implied warranty of
14 # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15 # GNU General Public License for more details.
f919f9d @trondeau Removed whitespace and added dtools/bin/remove-whitespace as a tool t…
trondeau authored
16 #
5d69a52 Houston, we have a trunk.
jcorgan authored
17 # You should have received a copy of the GNU General Public License
18 # along with GNU Radio; see the file COPYING. If not, write to
86f5c92 Updated FSF address in all files. Fixes ticket:51
eb authored
19 # the Free Software Foundation, Inc., 51 Franklin Street,
20 # Boston, MA 02110-1301, USA.
f919f9d @trondeau Removed whitespace and added dtools/bin/remove-whitespace as a tool t…
trondeau authored
21 #
5d69a52 Houston, we have a trunk.
jcorgan authored
22
23 Random notes on coding conventions, some explanations about why things
24 aren't done differently, etc, etc,
25
26
eb5c624 added note about boost and DISTCHECK_CONFIGURE_FLAGS
eb authored
27 * Boost 1.35
28
f5dd2ac @marcusmueller Worked out a few kinks and anachronism in the README.*
marcusmueller authored
29 Boost 1.35 and later is fairly common in modern distributions.
30 If it isn't available for your system, please refer to
31 README.building-boost for instructions
eb5c624 added note about boost and DISTCHECK_CONFIGURE_FLAGS
eb authored
32
5d69a52 Houston, we have a trunk.
jcorgan authored
33 * C++ and Python
34
060afcd @marcusmueller completing the half sentence about when to use C++
marcusmueller authored
35 GNU Radio is a hybrid system. Some parts of the system are built in C++ and
36 some of it in Python. In general, prefer Python to C++ for its simplicity; for
37 performance-critical and system-related functionality use C++. Signal
38 processing primitives are still built in C++ for performance; the
39 Vector-Optimized Library of Kernels (VOLK) is directly accessible from C++.
5d69a52 Houston, we have a trunk.
jcorgan authored
40
41
42 * C++ namespaces
43
f5dd2ac @marcusmueller Worked out a few kinks and anachronism in the README.*
marcusmueller authored
44 GNU Radio is organized in modules. For example, the blocks of the gr-digital
45 module reside in the namespace gr::digital. Out-Of-Tree modules follow the
46 same convention, but should take care not to clash with the official modules.
5d69a52 Houston, we have a trunk.
jcorgan authored
47
48 * Naming conventions
49
50 Death to CamelCaseNames! We've returned to a kinder, gentler era.
51 We're now using the "STL style" naming convention with a couple of
f5dd2ac @marcusmueller Worked out a few kinks and anachronism in the README.*
marcusmueller authored
52 modifications. Refer to the classes in the official source tree for
53 examples.
5d69a52 Houston, we have a trunk.
jcorgan authored
54
55 With the exception of macros and other constant values, all
56 identifiers shall be lower case with words_separated_like_this.
57
58 Macros and constant values (e.g., enumerated values,
59 static const int FOO = 23) shall be in UPPER_CASE.
60
61
62 ** Class data members (instance variables)
63
64 All class data members shall begin with d_<foo>.
65
f5dd2ac @marcusmueller Worked out a few kinks and anachronism in the README.*
marcusmueller authored
66 The big benefit is when you're staring at a block of code it's obvious
5d69a52 Houston, we have a trunk.
jcorgan authored
67 which of the things being assigned to persist outside of the block.
68 This also keeps you from having to be creative with parameter names
69 for methods and constructors. You just use the same name as the
f919f9d @trondeau Removed whitespace and added dtools/bin/remove-whitespace as a tool t…
trondeau authored
70 instance variable, without the d_.
5d69a52 Houston, we have a trunk.
jcorgan authored
71
f5dd2ac @marcusmueller Worked out a few kinks and anachronism in the README.*
marcusmueller authored
72 class wonderfulness {
5d69a52 Houston, we have a trunk.
jcorgan authored
73 std::string d_name;
74 double d_wonderfulness_factor;
75
76 public:
f5dd2ac @marcusmueller Worked out a few kinks and anachronism in the README.*
marcusmueller authored
77 wonderfulness (std::string name, double wonderfulness_factor)
5d69a52 Houston, we have a trunk.
jcorgan authored
78 : d_name (name), d_wonderfulness_factor (wonderfulness_factor)
79 {
80 ...
81 }
82 ...
83 };
84
85
86 ** Class static data members (class variables)
87
88 All class static data members shall begin with s_<foo>.
89
90
91 ** File names
92
6cf806b @uwehermann README files: Fix typos.
uwehermann authored
93 Each significant class shall be contained in its own file.
5d69a52 Houston, we have a trunk.
jcorgan authored
94
95 * Storage management
96
97 Strongly consider using the boost smart pointer templates, scoped_ptr
98 and shared_ptr. scoped_ptr should be used for locals that contain
99 pointers to objects that we need to delete when we exit the current
100 scope. shared_ptr implements transparent reference counting and is a
101 major win. You never have to worry about calling delete. The right
102 thing happens.
103
104 See http://www.boost.org/libs/smart_ptr/smart_ptr.htm
105
106
107 * Unit tests
108
f5dd2ac @marcusmueller Worked out a few kinks and anachronism in the README.*
marcusmueller authored
109 Unit tests are a useful tool for development -- they are less of a tool
597b937 @trondeau Removing trailing/extra whitespaces before release.
trondeau authored
110 to prove others that you can write code that works like you defined it but help
f5dd2ac @marcusmueller Worked out a few kinks and anachronism in the README.*
marcusmueller authored
111 you and later maintainers identify corner cases, regressions and other malfunctions
597b937 @trondeau Removing trailing/extra whitespaces before release.
trondeau authored
112 of code.
5d69a52 Houston, we have a trunk.
jcorgan authored
113
f5dd2ac @marcusmueller Worked out a few kinks and anachronism in the README.*
marcusmueller authored
114 GNU Radio has integrated versatile, easy to use testing facilities. Please refer to
115 http://gnuradio.org/redmine/projects/gnuradio/wiki/Coding_guide_impl#Unit-testing
5d69a52 Houston, we have a trunk.
jcorgan authored
116
d00c31f documented standard command line options and conventions
eb authored
117
118 * Standard command line options
119
120 When writing programs that are executable from the command line,
121 please follow these guidelines for command line argument names (short
122 and long) and types of the arguments. We list them below using the
123 Python optparse syntax. In general, the default value should be coded
124 into the help string using the "... [default=%default]" syntax.
125
f5dd2ac @marcusmueller Worked out a few kinks and anachronism in the README.*
marcusmueller authored
126 ** Mandatory options by gr::block
127
128 When designing flow graphs with the GNU Radio Companion, appropriate
597b937 @trondeau Removing trailing/extra whitespaces before release.
trondeau authored
129 option parsing will automatically be set up for you.
d00c31f documented standard command line options and conventions
eb authored
130
131 *** Audio source
132
133 Any program using an audio source shall include:
134
135 add_option("-I", "--audio-input", type="string", default="",
136 help="pcm input device name. E.g., hw:0,0 or /dev/dsp")
137
138 The default must be "". This allows an audio module-dependent default
139 to be specified in the user preferences file.
140
141
142 *** Audio sink
143
144 add_option("-O", "--audio-output", type="string", default="",
145 help="pcm output device name. E.g., hw:0,0 or /dev/dsp")
146
147 The default must be "". This allows an audio module-dependent default
148 to be specified in the user preferences file.
149
150
151 ** Standard options names by parameter
152
153 Whenever you want an integer, use the "intx" type. This allows the
154 user to input decimal, hex or octal numbers. E.g., 10, 012, 0xa.
155
156 Whenever you want a float, use the "eng_float" type. This allows the
157 user to input numbers with SI suffixes. E.g, 10000, 10k, 10M, 10m, 92.1M
158
159 If your program allows the user to specify values for any of the
160 following parameters, please use these options to specify them:
161
162
163 To specify a frequency (typically an RF center frequency) use:
164
165 add_option("-f", "--freq", type="eng_float", default=<your-default-here>,
166 help="set frequency to FREQ [default=%default]")
167
168
169 To specify a decimation factor use:
170
171 add_option("-d", "--decim", type="intx", default=<your-default-here>,
172 help="set decimation rate to DECIM [default=%default]")
173
174
175 To specify an interpolation factor use:
176
177 add_option("-i", "--interp", type="intx", default=<your-default-here>,
178 help="set interpolation rate to INTERP [default=%default]")
179
180
181 To specify a gain setting use:
182
183 add_option("-g", "--gain", type="eng_float", default=<your-default-here>,
184 help="set gain in dB [default=%default]")
185
186
187 If your application specifies both a tx and an rx gain, use:
188
189 add_option("", "--rx-gain", type="eng_float", default=<your-default-here>,
190 help="set receive gain in dB [default=%default]")
191
192 add_option("", "--tx-gain", type="eng_float", default=<your-default-here>,
193 help="set transmit gain in dB [default=%default]")
194
195
196 To specify the number of channels of something use:
197
198 add_option("-n", "--nchannels", type="intx", default=1,
199 help="specify number of channels [default=%default]")
200
201
202 To specify an output filename use:
203
204 add_option("-o", "--output-filename", type="string", default=<your-default-here>,
205 help="specify output-filename [default=%default]")
206
207
208 To specify a rate use:
209
210 add_option("-r", "--bit-rate", type="eng_float", default=<your-default-here>,
211 help="specify bit-rate [default=%default]")
212 or
213
214 add_option("-r", "--sample-rate", type="eng_float", default=<your-default-here>,
215 help="specify sample-rate [default=%default]")
f919f9d @trondeau Removed whitespace and added dtools/bin/remove-whitespace as a tool t…
trondeau authored
216
d00c31f documented standard command line options and conventions
eb authored
217
218 If your application has a verbose option, use:
219
220 add_option('-v', '--verbose', action="store_true", default=False,
221 help="verbose output")
222
223
f919f9d @trondeau Removed whitespace and added dtools/bin/remove-whitespace as a tool t…
trondeau authored
224 If your application allows the user to specify the "fast USB" options, use:
d00c31f documented standard command line options and conventions
eb authored
225
226 add_option("", "--fusb-block-size", type="intx", default=0,
6cf806b @uwehermann README files: Fix typos.
uwehermann authored
227 help="specify fast USB block size [default=%default]")
d00c31f documented standard command line options and conventions
eb authored
228
229 add_option("", "--fusb-nblocks", type="intx", default=0,
6cf806b @uwehermann README files: Fix typos.
uwehermann authored
230 help="specify number of fast USB blocks [default=%default]")
Something went wrong with that request. Please try again.