Improve Table of Contents

This commit is contained in:
Carles Fernandez 2022-11-12 09:53:36 +01:00
parent 16f0b4c862
commit 20f4b539a4
No known key found for this signature in database
GPG Key ID: 4C583C52B0C3877D
1 changed files with 166 additions and 161 deletions

327
README.md
View File

@ -59,58 +59,60 @@ information about this open-source, software-defined GNSS receiver.
<summary><b>(click to expand)</b></summary>
<!-- MarkdownTOC -->
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)
<!-- /MarkdownTOC -->
</details>
@ -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:
<a name="download-and-build-linux"></a>
```
$ 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
```
### <a name="download-and-build-linux">Clone GNSS-SDR's Git repository</a>:
### 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").
## <a name="macosx">macOS</a>
## 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).
#### <a name="macports">Macports</a>
### 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
```
#### <a name="homebrew">Homebrew</a>
### 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