Move 3-6 to 3-7

= Guide to help move from 3.6 to 3.7 =

Cmake structure for out-of-tree projects
To link against GNU Radio in 3.7:


 * Remove FindGnuradioCore.cmake and FindGruel.cmake,

Replace with FindGnuradioRuntime.cmake


 * Remove all GRUEL_ references and replace GNURADIO_CORE variables with GNURADIO_RUNTIME


 * Update #include&lt;gruel/attributes.h&gt; to &lt;gnuradio/attributes.h&gt;

Reorganized Blocks
We documented where we moved all blocks from gnuradio-core into their respective components. This can be found in a Google doc:

http://ow.ly/mDplO

Help in documenting where Python modules moved, which we did not track since it was simply a move and not a recoding, would be welcome here.

Changes in Blocks
gr::filter::freq_xlating_fir_filter_XXX


 * The center_freq API argument is now the actual center frequency of the incoming signal.
 * In previous versions of GNU Radio, this was the negative of the center frequency. To fix, just change the sign.

gr::blocks::wavfile_sink


 * When a lock call is made to a flowgraph, in order to make changes to it, all wavfile_sink blocks in the flowgraph will stop recording and close their currently open file.
 * In previous versions of GNU Radio, wavfile_sink would only pauses recording when a lock call was made and resume recording to the same file after a subsequent unlock call was made.

Code structure for out-of-tree modules
The file structure is changing from this format:

gr-modname/include/modname_blockname.h gr-modname/lib/modname_blockname.cc ...to:

gr-modname/include/modname/blockname.h gr-modname/lib/blockname_impl.h gr-modname/lib/blockname_impl.cc Some things to note:


 * - This public header file declares an abstract class. Public methods declared here are pure virtual and should be of the form:
 * since these must be implemented by a subclass (the  class will be the concrete class).
 * - This private header file declares member variables and concrete implementations of methods declared in the abstract class.
 * - This file defines the member variables and provides the concrete implementations of methods in.

Make sure the methods in  are declared pure virtual so that   can remain an abstract class. If  is not abstract, your code may compile but SWIG will interpret the declaration as the concrete class instead of your   class. At runtime this will cause an error like  when the Python interpreter attempts to load your SWIGged object code. The new coding structure is discussed in great detail here: Blocks Coding Guide.

Recognizing Namespace Changes
All blocks and classes are under namespace in GNU Radio now. So make sure that OOT code understands this.

One big issue to remember is the changes to the class inheritance:

class MODNAME_API classname : public gr_block class MODNAME_API classname : public gr_sync_block class MODNAME_API classname : public gr_sync_decimator class MODNAME_API classname : public gr_sync_interpolator ... becomes:

class MODNAME_API classname : public gr::block class MODNAME_API classname : public gr::sync_block class MODNAME_API classname : public gr::sync_decimator class MODNAME_API classname : public gr::sync_interpolator

Update to the private implementation structure in gnuradio-runtime:

 * Includes will change in form from these examples:

#include #include #include #include ...to:


 * 1) include
 * 2) include
 * 3) include
 * 4) include
 * The C++ classes in the GNU Radio runtime will be accessed through the 'gr' namespace, so class declarations that look like:

class my_foo_block : public gr_sync_block {...}; class my_top_block : public gr_top_block {...}; ...will become:

class my_foo_block : public gr::sync_block {...}; class my_top_block : public gr::top_block {...};
 * Finally, creating instances of classes in the runtime will use the static class make function, instead of calling the separate gr_make_* calls. Thus:

gr_make_io_signature(1, 1, sizeof(gr_complex)) gr_make_io_signature2(1, 1, sizeof(gr_complex)) ...becomes:

gr::io_signature::make(1, 1, sizeof(gr::complex)) gr::io_signature::make2(1, 1, sizeof(gr::complex))
 * Python and GRC code won't be affected by this change.

Include Directories

 * As already hinted at above, all headers should be included from the gnuradio directory:


 * 1) include
 * Include directories in your project should not include gnuradio. You would use /usr/local/include. Do not use /usr/local/include/gnuradio.
 * With the renaming of files, using the include/gnuradio directly could cause name clashes with other projects or standard header files. In particular, #include  could potentially find gnuradio/math.h instead of the intended system math.h.

Classes, Structs, and Typedefs
Classes and structs are all renamed and under namespaces. So  becomes. This includes  - &gt;   and   - &gt;.

However, typedefs have not been changed. This includes:

gr_complex gr_vector_void_star gr_vector_const_void_star gr_vector_int

PMT

 * Import PMT in Python as  (instead of  ).


 * All PMT function names have dropped the  prefix. So in Python use   instead of   and in C++ use   instead of.

Restructure of GRC Category Names to Help Transition

 * We removed all of the old blocks from the GRC component tree.


 * This does not remove the blocks from GRC, so this does not affect GRC apps already created.


 * The change affects how we find blocks, and the blocks in the category tree are now (almost) all from 3.7.


 * We have changed the category names and reorged all of the blocks, so it might take a little bit of getting used to. But we feel the new categorization is more intuitive.

 The next section shows the new category names used.


 * When using the component tree, almost all the blocks listed there are the new blocks for 3.7.


 * When opening your GRC files now, if you are using a block that is from 3.6, the name will be: &quot;Block name (old)&quot;.

 This is to make it clear that you are using a pre-3.7 block.


 * The (old) name is to help identify where you can update to a new 3.7 block in your flowgraph.

 This will help prepare you for the conversion to v3.7

 A script can help migrating flowgraphs with many old blocks to the 3.7 versions. One attempt with only 15 blocks is at http://nathanwest.us/grc_to_37.sh :


 * 1) !/bin/bash


 * 1) Version 0.1
 * 2) run ./grc_to_37 .grc
 * 3) this will create a backup copy and attempt to convert the api calls to 3.7

GRCFILE=$1

cp $GRCFILE $GRCFILE.pre3.7upgrade_backup # I refuse to take responsibility for breaking your flowgraphs
 * 1) set up a list of partial regexps to change modules

list_of_block_changes=(

&quot;gr_peak_detector2_fb/blocks_peak_detector2_fb&quot;

&quot;gr_short_to_float/blocks_short_to_float&quot;

&quot;gr_diff_phasor_cc/digital_diff_phasor_cc&quot;

&quot;blks2_logpwrfft_x/logpwrfft_x&quot;

&quot;gr_rms_xx/blocks_rms_xx&quot;

&quot;gr_probe_density_b/digital_probe_density_b&quot;

&quot;gr_mute_xx/blocks_mute_xx&quot;

&quot;gr_agc_xx/analog_agc_xx&quot;

&quot;gr_ctcss_squelch_ff/analog_ctcss_squelch_ff&quot;

&quot;gr_diff_encoder_bb/digital_diff_encoder_bb&quot;

&quot;gr_pll_refout_cc/analog_pll_refout_cc&quot;

&quot;gr_uchar_to_float/blocks_uchar_to_float&quot;

&quot;gr_interp_fir_filter_xxx/interp_fir_filter_xxx&quot;

&quot;gr_udp_sink/blocks_udp_sink&quot;

&quot;gr_and_xx/blocks_and_xx&quot;

&quot;gr_keep_one_in_n/blocks_keep_one_in_n&quot;

&quot;gr_vector_sink_x/blocks_vector_sink_x&quot;

&quot;gr_freq_xlating_fir_filter_xxx/freq_xlating_fir_filter_xxx&quot;

&quot;gr_float_to_int/blocks_float_to_int&quot;

&quot;gr_file_source/blocks_file_source&quot;

&quot;gr_float_to_short/blocks_float_to_short&quot;

&quot;gr_fft_vxx/fft_vxx&quot;

&quot;gr_quadrature_demod_cf/analog_quadrature_demod_cf&quot;

&quot;gr_file_sink/blocks_file_sink&quot;

&quot;gr_pfb_clock_sync_xxx/digital_pfb_clock_sync_xxx&quot;

&quot;gr_multiply_const_vxx/blocks_multiply_const_vxx&quot;

&quot;gr_peak_detector_xb/blocks_peak_detector_xb&quot;

&quot;gr_noise_source_x/analog_noise_source_x&quot;

&quot;gr_simple_framer/digital_simple_framer&quot;

&quot;gr_delay/blocks_delay&quot;

&quot;gr_pfb_synthesizer_ccf/pfb_synthesizer_ccf&quot;

&quot;gr_short_to_char/blocks_short_to_char&quot;

&quot;gr_chunks_to_symbols_xx/digital_chunks_to_symbols_xx&quot;

&quot;gr_interleaved_short_to_complex/blocks_interleaved_short_to_complex&quot;

&quot;gr_frequency_modulator_fc/analog_frequency_modulator_fc&quot;

&quot;gr_xor_xx/blocks_xor_xx&quot;

&quot;gr_dpll_bb/analog_dpll_bb&quot;

&quot;gr_threshold_ff/blocks_threshold_ff&quot;

&quot;gr_nop/blocks_nop&quot;

&quot;gr_unpack_k_bits_bb/blocks_unpack_k_bits_bb&quot;

&quot;gr_max_xx/blocks_max_xx&quot;

&quot;gr_int_to_float/blocks_int_to_float&quot;

&quot;gr_stream_to_streams/blocks_stream_to_streams&quot;

&quot;blks2_wfm_rcv/analog_wfm_rcv&quot;

&quot;gr_fractional_interpolator_xx/fractional_interpolator_xx&quot;

&quot;gr_conjugate_cc/blocks_conjugate_cc&quot;

&quot;blks2_fm_demod_cf/analog_fm_demod_cf&quot;

&quot;gr_fir_filter_xxx/fir_filter_xxx&quot;

&quot;gr_null_source/blocks_null_source&quot;

&quot;gr_complex_to_arg/blocks_complex_to_arg&quot;

&quot;gr_pwr_squelch_xx/analog_pwr_squelch_xx&quot;

&quot;gr_descrambler_bb/digital_descrambler_bb&quot;

&quot;gr_copy/blocks_copy&quot;

&quot;gr_complex_to_mag/blocks_complex_to_mag&quot;

&quot;gr_throttle/blocks_throttle&quot;

&quot;gr_additive_scrambler_bb/digital_additive_scrambler_bb&quot;

&quot;gr_wavfile_sink/blocks_wavfile_sink&quot;

&quot;gr_vector_source_x/blocks_vector_source_x&quot;

&quot;gr_moving_average_xx/blocks_moving_average_xx&quot;

&quot;gr_char_to_short/blocks_char_to_short&quot;

&quot;blks2_fm_deemph/analog_fm_deemph&quot;

&quot;gr_pll_freqdet_cf/analog_pll_freqdet_cf&quot;

&quot;gr_or_xx/blocks_or_xx&quot;

&quot;blks2_fm_preemph/analog_fm_preemph&quot;

&quot;blks2_wfm_tx/analog_wfm_tx&quot;

&quot;gr_stream_to_vector/blocks_stream_to_vector&quot;

&quot;gr_glfsr_source_x/digital_glfsr_source_x&quot;

&quot;gr_map_bb/digital_map_bb&quot;

&quot;gr_sig_source_x/analog_sig_source_x&quot;

&quot;gr_transcendental/blocks_transcendental&quot;

&quot;gr_skiphead/blocks_skiphead&quot;

&quot;gr_hilbert_fc/hilbert_fc&quot;

&quot;blks2_nbfm_rx/analog_nbfm_rx&quot;

&quot;random_source_x/analog_random_source_x&quot;

&quot;gr_complex_to_real/blocks_complex_to_real&quot;

&quot;gr_null_sink/blocks_null_sink&quot;

&quot;gr_float_to_complex/blocks_float_to_complex&quot;

&quot;gr_multiply_xx/blocks_multiply_xx&quot;

&quot;gr_simple_correlator/digital_simple_correlator&quot;

&quot;gr_sample_and_hold_xx/blocks_sample_and_hold_xx&quot;

&quot;blks2_pfb_channelizer_ccf/pfb_channelizer_ccf&quot;

&quot;gr_goertzel_fc/goertzel_fc&quot;

&quot;gr_complex_to_mag_squared/blocks_complex_to_mag_squared&quot;

&quot;gr_packed_to_unpacked_xx/blocks_packed_to_unpacked_xx&quot;

&quot;blks2_standard_squelch/analog_standard_squelch&quot;

&quot;blks2_am_demod_cf/analog_am_demod_cf&quot;

&quot;gr_and_const_xx/blocks_and_const_xx&quot;

&quot;gr_unpacked_to_packed_xx/blocks_unpacked_to_packed_xx&quot;

&quot;gr_probe_avg_mag_sqrd_x/analog_probe_avg_mag_sqrd_x&quot;

&quot;gr_channel_model/channels_channel_model&quot;

&quot;gr_divide_xx/blocks_divide_xx&quot;

&quot;gr_simple_squelch_cc/analog_simple_squelch_cc&quot;

&quot;gr_message_source/blocks_message_source&quot;

&quot;gr_sub_xx/blocks_sub_xx&quot;

&quot;gr_stream_mux/blocks_stream_mux&quot;

&quot;gr_burst_tagger/blocks_burst_tagger&quot;

&quot;gr_float_to_uchar/blocks_float_to_uchar&quot;

&quot;gr_scrambler_bb/digital_scrambler_bb&quot;

&quot;gr_streams_to_vector/blocks_streams_to_vector&quot;

&quot;gr_add_xx/blocks_add_xx&quot;

&quot;gr_feedforward_agc_cc/analog_feedforward_agc_cc&quot;

&quot;gr_iir_filter_ffd/iir_filter_ffd&quot;

&quot;blks2_stream_to_vector_decimator/blocks_stream_to_vector_decimator&quot;

&quot;gr_pn_correlator_cc/digital_pn_correlator_cc&quot;

&quot;gr_streams_to_stream/blocks_streams_to_stream&quot;

&quot;gr_rational_resampler_base_xxx/rational_resampler_base_xxx&quot;

&quot;gr_vector_to_streams/blocks_vector_to_streams&quot;

&quot;gr_interleave/blocks_interleave&quot;

&quot;gr_add_const_vxx/blocks_add_const_vxx&quot;

&quot;gr_message_sink/blocks_message_sink&quot;

&quot;gr_complex_to_imag/blocks_complex_to_imag&quot;

&quot;gr_vco_f/blocks_vco_f&quot;

&quot;gr_deinterleave/blocks_deinterleave&quot;

&quot;gr_argmax_xx/blocks_argmax_xx&quot;

&quot;gr_not_xx/blocks_not_xx&quot;

&quot;gr_udp_source/blocks_udp_source&quot;

&quot;gr_nlog10_ff/blocks_nlog10_ff&quot;

&quot;gr_diff_decoder_bb/digital_diff_decoder_bb&quot;

&quot;gr_phase_modulator_fc/analog_phase_modulator_fc&quot;

&quot;gr_complex_to_interleaved_short/blocks_complex_to_interleaved_short&quot;

&quot;gr_float_to_char/blocks_float_to_char&quot;

&quot;gr_head/blocks_head&quot;

&quot;gr_fft_filter_xxx/fft_filter_xxx&quot;

&quot;gr_cpfsk_bc/analog_cpfsk_bc&quot;

&quot;gr_vector_to_stream/blocks_vector_to_stream&quot;

&quot;gr_agc2_xx/analog_agc2_xx&quot;

&quot;gr_pll_carriertracking_cc/analog_pll_carriertracking_cc&quot;

&quot;gr_repeat/blocks_repeat&quot;

&quot;gr_filter_delay_fc/filter_delay_fc&quot;

&quot;blks2_rational_resampler_xxx/rational_resampler_xxx&quot;

&quot;gr_char_to_float/blocks_char_to_float&quot;

&quot;gr_integrate_xx/blocks_integrate_xx&quot;

&quot;gr_wavfile_source/blocks_wavfile_source&quot;

&quot;gr_complex_to_float/blocks_complex_to_float&quot;

&quot;gr_single_pole_iir_filter_xx/single_pole_iir_filter_xx&quot;

&quot;blks2_nbfm_tx/analog_nbfm_tx&quot;

&quot;blks2_wfm_rcv_pll/analog_wfm_rcv_pll&quot;

&quot;const_source_x/analog_const_source_x&quot;

&quot;blks2_pfb_arb_resampler_ccf/pfb_arb_resampler_xxx&quot;

)

for block in &quot;${list_of_block_changes[@]}&quot;

do

sed --in-place &quot;/&lt;key/s/$block/g&quot; $GRCFILE


 * 1) only replace the keys lines because otherwise


 * 1) block ids can get clobbered if there are 2 of the same block


 * 1) one old, and one new that both use grc generated ids

done


 * The search box will return all blocks found, including the (old) blocks, so you can still get access to these, if you really want.

Note. Not all GRC blocks were converted this way on master. A lot of the hierarchical blocks that had a GRC component were not necessarily moved over to the new components on the master branch. So you might still find a few problems when opening up old GRC files in 3.7.

To see the list of blocks that are still being pulled in the old way, you can look at grc/blocks/block_tree.xml in the source code, or it is installed into ${prefix}/share/gnuradio/blocks/block_tree.xml.

This should really help with transitioning your work to 3.7 when you need to and in the meantime will not affect your current, running systems in anyway but looks.

GRC and Doxygen Components
We have completely overhauled the category naming scheme in both the Doxygen manual and in GRC.

Click Here for a spreadsheet listing all of the blocks and which categories they are in

The following categories (and the Doxygen  group name for markup) are:

VOLK Changes
We have updated the VOLK directory structure to help in the automating of tests and building of new VOLK kernels, including the use of out-of-tree libraries of VOLK functions.

Also, a handful of the original VOLK kernels used  as the parameter while most used. This inconsistency made it difficult to automate some tests, and it made it more difficult to work with VOLK if you didn't know which style you were working with. The VOLK in 3.7 has updated this so that all blocks now use.

The affected kernels due to the 's/num_bytes/num_items/g' change are:

volk_16i_max_star_16i_a.h volk_16i_max_star_horizontal_16i_a.h volk_16i_permute_and_scalar_add_a.h volk_16i_x4_quad_max_star_16i_a.h volk_16i_x5_add_quad_16i_x4_a.h volk_32f_x3_sum_of_poly_32f_a.h volk_32fc_index_max_16u_a.h volk_32fc_x2_conjugate_dot_prod_32fc_a.h volk_32fc_x2_conjugate_dot_prod_32fc_u.h volk_32fc_x2_dot_prod_32fc_a.h volk_32fc_x2_s32f_square_dist_scalar_mult_32f_a.h volk_32fc_x2_square_dist_32f_a.h