From 20f4b539a44f561cf9ecb252b13ff7bb94b8cc63 Mon Sep 17 00:00:00 2001 From: Carles Fernandez Date: Sat, 12 Nov 2022 09:53:36 +0100 Subject: [PATCH] Improve Table of Contents --- README.md | 327 +++++++++++++++++++++++++++--------------------------- 1 file changed, 166 insertions(+), 161 deletions(-) diff --git a/README.md b/README.md index 59742d294..d4c3485b0 100644 --- a/README.md +++ b/README.md @@ -59,58 +59,60 @@ information about this open-source, software-defined GNSS receiver. (click to expand) -1. [How to build GNSS-SDR](#how-to-build-gnss-sdr) +1. [Table of Contents](#table-of-contents) +2. [How to build GNSS-SDR](#how-to-build-gnss-sdr) 1. [GNU/Linux](#gnulinux) 1. [Alternative 1: Install dependencies using software packages](#alternative-1-install-dependencies-using-software-packages) - - [Debian / Ubuntu](#debian--ubuntu) - - [Arch Linux](#arch-linux) - - [CentOS](#centos) - - [Fedora](#fedora) - - [OpenSUSE](#opensuse) - - [Rocky Linux](#rocky-linux) - 1. [Alternative 2: Install dependencies using PyBOMBS](#alternative-2-install-dependencies-using-pybombs) - - [Manual installation of other required dependencies](#manual-installation-of-other-required-dependencies) - - [Armadillo](#install-armadillo-a-c-linear-algebra-library) - - [gflags](#install-gflags-a-commandline-flags-processing-module-for-c) - - [google-glog](#install-glog-a-library-that-implements-application-level-logging) - - [googletest](#download-the-google-c-testing-framework-also-known-as-google-test) - - [GnuTLS or OpenSSL](#install-the-gnutls-or-openssl-libraries) - - [matio](#install-matio-matlab-mat-file-io-library) - - [Protocol Buffers](#install-protocol-buffers-a-portable-mechanism-for-serialization-of-structured-data) - - [pugixml](#install-pugixml-a-light-weight-c-xml-processing-library) - 1. [Clone GNSS-SDR's Git repository](#clone-gnss-sdrs-git-repository) - 1. [Build and install GNSS-SDR](#build-and-install-gnss-sdr) - - [Build OsmoSDR support (optional)](#build-osmosdr-support-optional) - - [Build IIO support (optional)](#build-fmcomms2-based-sdr-hardware-support-optional) - - [Build OpenCL support (optional)](#build-opencl-support-optional) - - [Build CUDA support (optional)](#build-cuda-support-optional) - - [Build a portable binary](#build-a-portable-binary) - 1. [macOS](#macos) + 1. [Debian / Ubuntu](#debian--ubuntu) + 2. [Arch Linux](#arch-linux) + 3. [CentOS](#centos) + 4. [Fedora](#fedora) + 5. [openSUSE](#opensuse) + 6. [Rocky Linux](#rocky-linux) + 2. [Alternative 2: Install dependencies using PyBOMBS](#alternative-2-install-dependencies-using-pybombs) + 3. [Manual installation of other required dependencies](#manual-installation-of-other-required-dependencies) + 1. [Install Armadillo, a C++ linear algebra library](#install-armadillo-a-c-linear-algebra-library) + 2. [Install Gflags, a commandline flags processing module for C++](#install-gflags-a-commandline-flags-processing-module-for-c) + 3. [Install Glog, a library that implements application-level logging](#install-glog-a-library-that-implements-application-level-logging) + 4. [Install the GnuTLS or OpenSSL libraries](#install-the-gnutls-or-openssl-libraries) + 5. [Install Matio, MATLAB MAT file I/O library](#install-matio-matlab-mat-file-io-library) + 6. [Install Protocol Buffers, a portable mechanism for serialization of structured data](#install-protocol-buffers-a-portable-mechanism-for-serialization-of-structured-data) + 7. [Install Pugixml, a light-weight C++ XML processing library](#install-pugixml-a-light-weight-c-xml-processing-library) + 8. [Download GoogleTest](#download-googletest) + 4. [Clone GNSS-SDR's Git repository](#clone-gnss-sdrs-git-repository) + 5. [Build and install GNSS-SDR](#build-and-install-gnss-sdr) + 1. [Build OSMOSDR support (OPTIONAL)](#build-osmosdr-support-optional) + 2. [Build FMCOMMS2 based SDR Hardware support (OPTIONAL)](#build-fmcomms2-based-sdr-hardware-support-optional) + 3. [Build OpenCL support (OPTIONAL)](#build-opencl-support-optional) + 4. [Build CUDA support (OPTIONAL)](#build-cuda-support-optional) + 5. [Build a portable binary](#build-a-portable-binary) + 2. [macOS](#macos) 1. [Macports](#macports) - 1. [Homebrew](#homebrew) - 1. [Build GNSS-SDR](#build-gnss-sdr) - 1. [Other builds](#other-builds) -1. [Updating GNSS-SDR](#updating-gnss-sdr) -1. [Getting started](#getting-started) -1. [Using GNSS-SDR](#using-gnss-sdr) - 1. [Control Plane](#control-plane) + 2. [Homebrew](#homebrew) + 3. [Other package managers](#other-package-managers) + 4. [Build GNSS-SDR](#build-gnss-sdr) + 3. [Other builds](#other-builds) +3. [Updating GNSS-SDR](#updating-gnss-sdr) +4. [Getting started](#getting-started) +5. [Using GNSS-SDR](#using-gnss-sdr) + 1. [Control plane](#control-plane) 1. [Configuration](#configuration) - 1. [GNSS block factory](#gnss-block-factory) - 1. [Signal Processing Plane](#signal-processing-plane) + 2. [GNSS block factory](#gnss-block-factory) + 2. [Signal Processing plane](#signal-processing-plane) 1. [Signal Source](#signal-source) - 1. [Signal Conditioner](#signal-conditioner) - - [Data type adapter](#data-type-adapter) - - [Input filter](#input-filter) - - [Resampler](#resampler) - 1. [Channel](#channel) - - [Acquisition](#acquisition) - - [Tracking](#tracking) - - [Decoding of the navigation message](#decoding-of-the-navigation-message) - 1. [Observables](#observables) - 1. [Computation of Position, Velocity and Time](#computation-of-position-velocity-and-time) -1. [About the software license](#about-the-software-license) -1. [Publications and Credits](#publications-and-credits) -1. [Ok, now what?](#ok-now-what) + 2. [Signal Conditioner](#signal-conditioner) + 1. [Data type adapter](#data-type-adapter) + 2. [Input filter](#input-filter) + 3. [Resampler](#resampler) + 3. [Channel](#channel) + 1. [Acquisition](#acquisition) + 2. [Tracking](#tracking) + 3. [Decoding of the navigation message](#decoding-of-the-navigation-message) + 4. [Observables](#observables) + 5. [Computation of Position, Velocity and Time](#computation-of-position-velocity-and-time) +6. [About the software license](#about-the-software-license) +7. [Publications and Credits](#publications-and-credits) +8. [Ok, now what?](#ok-now-what) @@ -118,7 +120,7 @@ information about this open-source, software-defined GNSS receiver. # How to build GNSS-SDR This section describes how to set up the compilation environment in GNU/Linux or -[macOS / Mac OS X](#macosx), and to build GNSS-SDR. See also our +[macOS / Mac OS X](#macos), and to build GNSS-SDR. See also our [build and install page](https://gnss-sdr.org/build-and-install/ "GNSS-SDR's Build and Install"). ## GNU/Linux @@ -197,7 +199,7 @@ above. Install `libtool`, `automake` and `libhdf5-dev` instead. You will also need `python-six`. Once you have installed these packages, you can jump directly to -[download the source code and build GNSS-SDR](#download-and-build-linux). +[download the source code and build GNSS-SDR](#clone-gnss-sdrs-git-repository). #### Arch Linux @@ -210,7 +212,7 @@ $ pacman -S gcc make cmake pkgconf git boost boost-libs log4cpp libvolk gnuradio ``` Once you have installed these packages, you can jump directly to -[download the source code and build GNSS-SDR](#download-and-build-linux). +[download the source code and build GNSS-SDR](#clone-gnss-sdrs-git-repository). #### CentOS @@ -229,7 +231,7 @@ $ sudo yum install make automake gcc gcc-c++ kernel-devel libtool \ ``` Once you have installed these packages, you can jump directly to -[download the source code and build GNSS-SDR](#download-and-build-linux). +[download the source code and build GNSS-SDR](#clone-gnss-sdrs-git-repository). #### Fedora @@ -275,7 +277,7 @@ $ zypper install cmake git gcc-c++ boost-devel libboost_atomic-devel \ ``` Once you have installed these packages, you can jump directly to -[download the source code and build GNSS-SDR](#download-and-build-linux). +[download the source code and build GNSS-SDR](#clone-gnss-sdrs-git-repository). #### Rocky Linux @@ -293,7 +295,7 @@ $ yum install -y make gcc gcc-c++ kernel-devel cmake git boost-devel \ ``` Once you have installed these packages, you can jump directly to -[download the source code and build GNSS-SDR](#download-and-build-linux). +[download the source code and build GNSS-SDR](#clone-gnss-sdrs-git-repository). ### Alternative 2: Install dependencies using PyBOMBS @@ -374,11 +376,11 @@ $ pybombs install armadillo gflags glog gnutls matio ``` or manually as explained below, and then please follow instructions on how to -[download the source code and build GNSS-SDR](#download-and-build-linux). +[download the source code and build GNSS-SDR](#clone-gnss-sdrs-git-repository). ### Manual installation of other required dependencies -#### Install [Armadillo](http://arma.sourceforge.net/ "Armadillo's Homepage"), a C++ linear algebra library: +#### Install [Armadillo](http://arma.sourceforge.net/ "Armadillo's Homepage"), a C++ linear algebra library ``` $ sudo apt-get install libblas-dev liblapack-dev # For Debian/Ubuntu/LinuxMint @@ -400,7 +402,7 @@ correspondingly. CMake will also generate a run-time armadillo library, which is a combined alias for all the relevant libraries present on your system (e.g., BLAS, LAPACK, and ATLAS). -#### Install [Gflags](https://github.com/gflags/gflags "Gflags' Homepage"), a commandline flags processing module for C++: +#### Install [Gflags](https://github.com/gflags/gflags "Gflags' Homepage"), a commandline flags processing module for C++ ``` $ wget https://github.com/gflags/gflags/archive/v2.2.2.tar.gz @@ -412,7 +414,7 @@ $ sudo make install $ sudo ldconfig ``` -#### Install [Glog](https://github.com/google/glog "Glog's Homepage"), a library that implements application-level logging: +#### Install [Glog](https://github.com/google/glog "Glog's Homepage"), a library that implements application-level logging ``` $ wget https://github.com/google/glog/archive/v0.6.0.tar.gz @@ -425,7 +427,73 @@ $ sudo make install $ sudo ldconfig ``` -#### Download the [Google C++ Testing Framework](https://github.com/google/googletest "Googletest Homepage"), also known as Google Test: +#### Install the GnuTLS or OpenSSL libraries + +``` +$ sudo apt-get install libgnutls-openssl-dev # For Debian/Ubuntu/LinuxMint +$ sudo yum install openssl-devel # For Fedora/CentOS/RHEL +$ sudo zypper install openssl-devel # For OpenSUSE +$ sudo pacman -S openssl # For Arch Linux +``` + +In case the [GnuTLS](https://www.gnutls.org/ "GnuTLS's Homepage") library with +openssl extensions package is not available in your GNU/Linux distribution, +GNSS-SDR can also work well with +[OpenSSL](https://www.openssl.org/ "OpenSSL's Homepage"). + +#### Install [Matio](https://github.com/tbeu/matio "Matio's Homepage"), MATLAB MAT file I/O library + +``` +$ wget https://github.com/tbeu/matio/releases/download/v1.5.23/matio-1.5.23.tar.gz +$ tar xvfz matio-1.5.23.tar.gz +$ cd matio-1.5.23 +$ ./configure +$ make +$ sudo make install +$ sudo ldconfig +``` + +#### Install [Protocol Buffers](https://developers.google.com/protocol-buffers/ "Protocol Buffers' Homepage"), a portable mechanism for serialization of structured data + +GNSS-SDR requires Protocol Buffers v3.0.0 or later. If the packages that come +with your distribution are older than that (_e.g._, Ubuntu 16.04 Xenial and +Debian 8 Jessie came with older versions), then you will need to install it +manually. First, install the dependencies: + +``` +$ sudo apt-get install autoconf automake libtool curl make g++ unzip +``` + +and then: + +``` +$ git clone https://github.com/protocolbuffers/protobuf.git +$ cd protobuf +$ git submodule update --init --recursive +$ ./autogen.sh +$ /configure +$ make -j$(nproc) +$ sudo make install +$ sudo ldconfig +``` + +For more options, please check the +[Protocol Buffers' installation instructions](https://github.com/protocolbuffers/protobuf/blob/main/src/README.md/). + +#### Install [Pugixml](https://pugixml.org/ "Pugixml's Homepage"), a light-weight C++ XML processing library + +``` +$ wget https://github.com/zeux/pugixml/releases/download/v1.13/pugixml-1.13.tar.gz +$ tar xvfz pugixml-1.13.tar.gz +$ cd pugixml-1.13 +$ mkdir build && cd build +$ cmake .. +$ make +$ sudo make install +$ sudo ldconfig +``` + +#### Download [GoogleTest](https://github.com/google/googletest "Googletest Homepage") ``` $ wget https://github.com/google/googletest/archive/release-1.12.1.zip @@ -462,71 +530,9 @@ environment variable is not defined, or the source code is not installed by a package, then it will download a fresh copy of the Google Test source code and will compile and link it for you. -#### Install the [GnuTLS](https://www.gnutls.org/ "GnuTLS's Homepage") or [OpenSSL](https://www.openssl.org/ "OpenSSL's Homepage") libraries: + -``` -$ sudo apt-get install libgnutls-openssl-dev # For Debian/Ubuntu/LinuxMint -$ sudo yum install openssl-devel # For Fedora/CentOS/RHEL -$ sudo zypper install openssl-devel # For OpenSUSE -$ sudo pacman -S openssl # For Arch Linux -``` - -In case the GnuTLS library with openssl extensions package is not available in -your GNU/Linux distribution, GNSS-SDR can also work well with OpenSSL. - -#### Install [Matio](https://github.com/tbeu/matio "Matio's Homepage"), MATLAB MAT file I/O library: - -``` -$ wget https://github.com/tbeu/matio/releases/download/v1.5.23/matio-1.5.23.tar.gz -$ tar xvfz matio-1.5.23.tar.gz -$ cd matio-1.5.23 -$ ./configure -$ make -$ sudo make install -$ sudo ldconfig -``` - -#### Install [Protocol Buffers](https://developers.google.com/protocol-buffers/ "Protocol Buffers' Homepage"), a portable mechanism for serialization of structured data: - -GNSS-SDR requires Protocol Buffers v3.0.0 or later. If the packages that come -with your distribution are older than that (_e.g._, Ubuntu 16.04 Xenial and -Debian 8 Jessie came with older versions), then you will need to install it -manually. First, install the dependencies: - -``` -$ sudo apt-get install autoconf automake libtool curl make g++ unzip -``` - -and then: - -``` -$ git clone https://github.com/protocolbuffers/protobuf.git -$ cd protobuf -$ git submodule update --init --recursive -$ ./autogen.sh -$ /configure -$ make -j$(nproc) -$ sudo make install -$ sudo ldconfig -``` - -For more options, please check the -[Protocol Buffers' installation instructions](https://github.com/protocolbuffers/protobuf/blob/main/src/README.md/). - -#### Install [Pugixml](https://pugixml.org/ "Pugixml's Homepage"), a light-weight C++ XML processing library: - -``` -$ wget https://github.com/zeux/pugixml/releases/download/v1.12/pugixml-1.12.tar.gz -$ tar xvfz pugixml-1.12.tar.gz -$ cd pugixml-1.12 -$ mkdir build && cd build -$ cmake .. -$ make -$ sudo make install -$ sudo ldconfig -``` - -### Clone GNSS-SDR's Git repository: +### Clone GNSS-SDR's Git repository ``` $ git clone https://github.com/gnss-sdr/gnss-sdr @@ -665,7 +671,7 @@ and then import the created project into Eclipse: After building the project, you will find the generated binaries at `eclipse/install`. -###### Build OSMOSDR support (OPTIONAL): +#### Build OSMOSDR support (OPTIONAL) Install the [OsmoSDR](https://osmocom.org/projects/sdr "OsmoSDR's Homepage") library and GNU Radio's source block: @@ -701,7 +707,7 @@ $ sudo make install (in order to disable the `Osmosdr_Signal_Source` compilation, you can pass `-DENABLE_OSMOSDR=OFF` to cmake and build GNSS-SDR again). -###### Build FMCOMMS2 based SDR Hardware support (OPTIONAL): +#### Build FMCOMMS2 based SDR Hardware support (OPTIONAL) Install the [libiio](https://github.com/analogdevicesinc/libiio.git) (>=v0.11), [libad9361](https://github.com/analogdevicesinc/libad9361-iio.git) (>=v0.1-1) @@ -757,7 +763,7 @@ The `Plutosdr_Signal_Source` offers a simpler manner to use the ADALM-PLUTO because implements only a subset of FMCOMMS2's parameters valid for those devices. -###### Build OpenCL support (OPTIONAL): +#### Build OpenCL support (OPTIONAL) In order to enable the building of blocks that use OpenCL, type: @@ -767,7 +773,7 @@ $ make $ sudo make install ``` -###### Build CUDA support (OPTIONAL): +#### Build CUDA support (OPTIONAL) In order to enable the building of blocks that use CUDA, NVIDIA's parallel programming model that enables graphics processing unit (GPU) acceleration for @@ -784,7 +790,7 @@ $ sudo make install Of course, you will also need a GPU that [supports CUDA](https://developer.nvidia.com/cuda-gpus "CUDA GPUs"). -###### Build a portable binary +#### Build a portable binary In order to build an executable that not depends on the specific SIMD instruction set that is present in the processor of the compiling machine, so @@ -804,7 +810,7 @@ substitutes a generic, non-SIMD implementation. More details can be found in our tutorial about [GNSS-SDR configuration options at building time](https://gnss-sdr.org/docs/tutorials/using-git/ "Configuration options at building time"). -## macOS +## macOS GNSS-SDR can be built on macOS (or the former Mac OS X), starting from 10.9 (Mavericks) and including 11 (Big Sur). If you still have not installed @@ -827,7 +833,7 @@ $ sudo xcodebuild -license Software pre-requisites can be installed using either [Macports](#macports) or [Homebrew](#homebrew). -#### Macports +### Macports First, [install Macports](https://www.macports.org/install.php). If you are upgrading from a previous installation, please follow the @@ -857,7 +863,7 @@ and you can activate a certain version by typing: $ sudo port select --set python python37 ``` -#### Homebrew +### Homebrew First, install [Homebrew](https://brew.sh/). Paste this in a terminal prompt: @@ -886,7 +892,32 @@ $ brew install --cask mactex # when completed, restart Terminal $ brew install graphviz doxygen ``` -#### Build GNSS-SDR +### Other package managers + +GNU Radio and other dependencies can also be installed using other package +managers than Macports, such as [Fink](http://www.finkproject.org/ "Fink"). +Since the version of Python that ships with OS X is great for learning but it is +not good for development, you could have another Python executable in a +non-standard location. If that is the case, you need to inform GNSS-SDR's +configuration system by defining the `PYTHON_EXECUTABLE` variable as: + +``` +$ cmake -DPYTHON_EXECUTABLE=/path/to/bin/python3 .. +``` + +In case you have installed Macports in a non-standard location, you can use: + +``` +$ cmake -DCMAKE_PREFIX_PATH=/opt/local -DUSE_MACPORTS_PYTHON=/opt/local/bin/python .. +``` + +changing `/opt/local` by the base directory in which your software is installed. + +The CMake script will create Makefiles that download, build and link Armadillo, +Gflags, Glog, Matio, Protocol Buffers, PugiXML and Google Test on the fly at +compile time if they are not detected in your machine. + +### Build GNSS-SDR Finally, you are ready to clone the GNSS-SDR repository, configure and build the software: @@ -933,32 +964,6 @@ the function to execute. It mimics GNU Radio's [VOLK](https://www.libvolk.org/) library, so if you still have not run `volk_profile`, this is a good moment to do so. -###### Other package managers - -GNU Radio and other dependencies can also be installed using other package -managers than Macports, such as [Fink](http://www.finkproject.org/ "Fink") or -[Homebrew](https://brew.sh/ "Homebrew"). Since the version of Python that ships -with OS X is great for learning but it is not good for development, you could -have another Python executable in a non-standard location. If that is the case, -you need to inform GNSS-SDR's configuration system by defining the -`PYTHON_EXECUTABLE` variable as: - -``` -cmake -DPYTHON_EXECUTABLE=/path/to/bin/python3 .. -``` - -In case you have installed Macports in a non-standard location, you can use: - -``` -$ cmake -DCMAKE_PREFIX_PATH=/opt/local -DUSE_MACPORTS_PYTHON=/opt/local/bin/python .. -``` - -changing `/opt/local` by the base directory in which your software is installed. - -The CMake script will create Makefiles that download, build and link Armadillo, -Gflags, Glog, Matio, Protocol Buffers, PugiXML and Google Test on the fly at -compile time if they are not detected in your machine. - ## Other builds - **Docker image**: A technology providing operating-system-level virtualization @@ -982,10 +987,10 @@ compile time if they are not detected in your machine. - **GNSS-SDR in embedded platforms**: we provide a Software Development Kit (SDK) based on [OpenEmbedded](http://www.openembedded.org/wiki/Main_Page) for cross-compiling GNSS-SDR in your desktop computer and for producing - executables that can run in embedded platforms, such as a Zedboard or a - Raspberry Pi 3. Visit - [Cross-compiling GNSS-SDR](https://gnss-sdr.org/docs/tutorials/cross-compiling/) - for instructions. + executables that can run in embedded platforms, such as Xilinx's Zynq and + ZynqMP architectures, Raspberry Pi, and many others. Please check + [yocto-geniux](https://github.com/carlesfernandez/yocto-geniux) for + instructions on how to build bootable images. # Updating GNSS-SDR