Talk:Draft-AN-445

Please leave comments below by clicking the "Add topic" tab, or to reply to an existing post, use a MediaWiki-style reply by starting a new line beginning with one more ':' than the entry replied to.

---

Please don't lead people down this path that don't have to

The default reaction to "how do I build GNU Radio" should be "do you really need to build it? Can you spell out why you need it?", as modern Linux distros bring modern GNU Radio and modern UHD.

I therefore would propose we keep this AN sweet and short – start with a warning that if the reader wants the modern versions listed on InstallingGR, then they should not even read this document any further.

I'd also point out that installing Linux should probably, for the documenting party's sake, be considered out of scope entirely. We can recommend some Linux distro, but Ettus certainly has no interest in supporting customers setting up their Linux! My sad experience with this is that you don't even start pointing out specific tools, or you're suddenly the support engineer for a bunch of angry defense contractor PMs.

We should also strike all the lists of dependencies to install; apt build-dep gnuradio uhd-host does the same, but stays up to date. (same exists for basically any other platform) If the distribution knowledge of build-time dependencies is wrong, we should work with upstream to fix that. Mait would like that.

Generally, any documentation that boils down to "copy these lines of code into your terminal and hit enter" should actually be a shell script that is well-commented. Taking this thought one step further, they should actually not just be shell scripts, but be the scripts run by a debian/ubuntu package. Every recipe that we can document well enough for it to be foolproof, proves that we can actually build these packages ourselves. We could be Ubuntu packaging off Josh's shoulders and offering Ubuntu package repos for:

1. latest-release UHD builds and exactly the GNU Radio that Ubuntu ships built against that UHD, so that all things using GNU Radio but not GR directly stay compatible
2. latest-release UHD builds and latest-release GNU Radio built against that UHD
3. nightly UHD builds and latest-release GNU Radio built against that UHD
4. nightly UHD builds and nightly GNU Radio built against that UHD

(more important to have 1., than to have 2., … from an Ettus point of view)

Ettus does have good PPAs for its current UHD releases, so no customer should have to build UHD themselves to code with UHD; and because we care about the GNU Radio-using customers as well, Ettus should be packaging GNU Radio built against these versions of UHD as well. That closes the gap where currently, when a user installs GNU Radio from Ubuntu, but then installs UHD from the Ettus PPA, they still have the old UHD used by their GNU Radio, but the images downloader, uhd_usrp_probe and so on are the modern UHD. That is not desirable in any way! The users don't know why they can't download the right packages, and why things break at every corner. No; installing (current situation) UHD 4.5.0.0 uhd-host and thus libuhd-4.5 from Ettus' PPA should uninstall the Ubuntu 20.04 libuhd-3.15, and thus uninstall the ubuntu version of gnuradio-3.8. Replacing that, it should install a compatible gnuradio-3.8 built against UHD 4.5.

UHD is the single most common reason Linux GNU Radio users (not developers) still build GNU Radio from source. GNU Radio has long left "a user needs to know how to build complex software such as UHD and GNU Radio from source" behind it. We should as well!

Marcus Müller, the (talk) 20:31, 23 September 2023 (UTC)

Re: RFNoC: GNU Radio 3.10 comes with gr-uhd with direct RFNoC 4 support; we no longer need to document gr-ettus usage, as that's dead. yay! Even with RFNoC, a user of modern Ubuntu needs not build anything from source. Marcus Müller, the (talk) 20:35, 23 September 2023 (UTC)

From Barry Duggan

The Draft-AN-445 was patterned after the Ettus doc, but IMO, AN-445 should contain only the following sections:

• Application Note Number
• Abstract
• Devices
• Update and Install dependencies
• Installing UHD from PPA
• Configuring USB
• Configuring Ethernet
• Connect the USRP
• Thread priority scheduling
• Building and installing GNU Radio from source code

That sounds like a very reasonable scope; I'd guess the USB/Ethernet setup sections would mostly be referring to existing ANs, or are we planning to include these directly? (wikipedia-style reply: start a new line starting with one more : than the line replied to) Marcus Müller, the (talk) 17:35, 24 September 2023 (UTC)

The USB and Ethernet sections are just a few lines of code, so I included them directly. Barry Duggan Sept. 30

Proposal for section "Installing the latest UHD toolchain and GNU Radio on Ubuntu"

Ettus offers PPAs (i.e., packages) for UHD releases, so that Ubuntu users don't have to manually build – let's exploit that fact!

Installing the latest UHD toolchain and GNU Radio on Ubuntu

Effort Estimate	5 - 10 min reading / work 5 to 90 min unattended build time, depending on the machine

Ettus offers a repository of up-to-date UHD software releases for users running Ubuntu Linux. This so-called PPA (Personal Package Archive) can be activated by running the following commands:

sudo apt-get install -y software-properties-common  # install the "add-apt-repository" tool, which allows us to set up PPAs (see below)
#    ^       ^        ^ ^––––––––––––––––––––––––^
#    |       |        |             |
#    `—–––––––––––––––––––––––––––––––––––––––––––– apt-get is the debian/Ubuntu package manager
#            |        |             |
#            `––––––––––––––––––––––––––––––––––––– tell apt-get to install software
#                     |             |
#                     `–––––––––––––––––––––––––––– don't ask me! Assume (y)es, I really wanted to install this
#                                   |
#                                   `—––––––––––––– list of packages to install: only one, the software-properties-common package

sudo add-apt-repository ppa:ettusresearch/uhd       # add the "ettusresearch/uhd" package repository as source for packages
                                                    # that can be installed using apt-get / apt

You can then install the libuhd, libuhd-dev and uhd-host packages from Ettus, instead of using the potentially older Ubuntu-shipped ones.

sudo apt-get update                                 # refresh package lists
sudo apt-get install -y uhd-host libuhd libuhd-dev 
#    ^       ^        ^ ^––––––^ ^––––^ ^––––––––^
#    |       |        |     |       |       |      
#    `—–––––––––––––––––––––––––––––––––––––––––––– apt-get is the debian/Ubuntu package manager
#            |        |     |       |       |      
#            `––––––––––––––––––––––––––––––––––––– tell apt-get to install software
#                     |     |       |       |      
#                     `–––––––––––––––––––––––––––– don't ask me! Assume (y)es, I really wanted to install this
#                           |       |       |
#                           `–––––––+–––––––+–––––– list of packages to install

However, the Ubuntu-shipped GNU Radio package would still use the Ubuntu version of UHD, not the one from Ettus. To solve this issue, whilst keeping compatibility with all GNU Radio-based packages that Ubuntu ships (gr-osmosdr, gqrx, …), you will have to rebuild Ubuntu's gnuradio packages. This happens in the following five steps:

1. Enable the Ubuntu package source repositories
2. Install the gnuradio package's build-dependencies
3. Download the gnuradio package and rebuild it
4. Install the freshly built package(s)
5. Fix the version of the installed libgnuradio-uhd package, so an update from Ubuntu doesn't replace your gnuradio package with one using the original Ubuntu UHD.

In detail, after you've set up the PPA as described above, you'd have to go through the following steps:

1. Enable the Ubuntu package source repositories

Either using the software settings in your desktop environment (settings->Software->checkmark on "Source Code"), or by editing /etc/apt/sources.list, add (uncomment) the identical lines, starting with deb-src instead of deb below each deb line.

Run sudo apt-get update to make your system aware that it now knows how to get source code for packages.

2. Install the gnuradio package's build-dependencies

sudo apt-get build-dep -y gnuradio
#    ^       ^         ^  ^
#    |       |         |  |
#    `–––––––––––––––––––––––––––– The debian/Ubuntu package manager
#            |         |  |
#            `–––––––––––––––––––– ask apt-get to determine and install all packages
#                      |  |        needed to build the specified target package
#                      |  |
#                      `–––––––––– assume "yes"
#                         |
#                         `––––––– the package(s) for which to install the build de-
#                                  pendencies

sudo apt-get install -y dpkg-dev
#                       ^
#                       `––––––––– dpkg-dev is needed to directly build an installable
#                                  package out of package sources (see next step)

3. Download the gnuradio package and rebuild it

No sudo required! We'll create a new directory gnuradio-pkg in our home directory, change into that directory, and into that directory download the sources of the Ubuntu gnuradio package. We instruct apt-get to re-build the freshly downloaded source packages right away:

cd                              # changes into the home directory (~)
mkdir gnuradio-pkg              # makes a new directory called "gnuradio-pkg"
cd gnuradio-pkg                 # changes into the newly created "gnuradio-pkg" directory
apt-get source --build gnuradio
# ^     ^      ^       ^
# |     |      |       |
# `————————————————————————————— apt-get has many features, including:
#       |      |       |
#       `––––––––––––––––––––––– tell apt-get to get source package(s)
#              |       |
#              `–––––––––––––––– and tell it to build the binary packages right after downloading
#                      |
#                      `–––––––– which packages: only gnuradio

You're left with new .deb package files in ~/gnuradio-pkg.

4. Install the freshly built package(s)

cd ~/gnuradio-pkg 
sudo apt-get install -y ./*.deb  # installs all the .deb packages from the local directory

5. Fix the version of the installed package

sudo apt-mark hold libgnuradio-uhd\*

This tells apt-get's internal database that we do not wish to automatically update GNU Radio's UHD component.

Revision / update of UHD and GNU Radio install docs

Documents affected

• LinuxInstall
  • Intro
  • LinuxInstall#Distributions_and_Commands
  • LinuxInstall#Ubuntu_PPA_Installation
    • Attention
  • LinuxInstall#From_Source
    • Replace 4.2 and 4.3

• InstallingGRFromSource_on_Raspberry_Pi

• AN-445 https://kb.ettus.com/Building_and_Installing_the_USRP_Open-Source_Toolchain_(UHD_and_GNU_Radio)_on_Linux

• Draft-AN-445 (GNU Radio version)