Raspberry Pi C++ Header Documentation

Question

Is there some sort of documentation for what kind of headers you can include in c++ files when writing programs for Raspberry Pi or linux in general?

For instance I found this great guide on how to access the SPI bus from the Pi using c++ ( http://hertaville.com/2013/07/24/interfacing-an-spi-adc-mcp3008-chip-to-the-raspberry-pi-using-c/ )

I was able to take the code and apply it to my situation and was succesfully able to talk to an nRF24L01+ RF module and I am able to command the chip etc.

But as I started trying to investigate what the code does (because I like to know how code that I get from the internet works) I get lost very quickly. For instance how did the author of that code know to include the header files he did:

#include <unistd.h>
#include <stdint.h>
#include <fcntl.h>
#include <sys/ioctl.h>
#include <linux/spi/spidev.h>
#include <stdio.h>
#include <errno.h>
#include <stdlib.h>
#include <string>
#include <iostream>

I know what the ones such as "iostream" do but I thought I would approach it by Googling those header file names such as ("unistd.h") but no luck. I found lots of info but none pertaining to the Pi, and the little bit I did only started referencing other header files and code. Is this too much to try and learn, like would I effectively be trying to learn the linux kernel? Are there any good books for this type of stuff?

And back to my original question is there any kind of online (or offline for that matter) documentation for what header files you can include in your c++ projects on the Pi and what functionality they all add?

I found this ( http://www.cplusplus.com/reference/ ) which has the standard files, but how do you know about all the non-standard header files and corresponding functionality?

All thoughts and help are appreciated, thanks! Wesley

Edit 1

Here is the image showing the output of the "ls /usr/include" command:

Answer 1

TL/DR : I've tried to have a general introduction to this topic below. If you are a more hands-on type and want to skip the wall of text, jump to the end. There are some tutorial links down there. Jump in -- getting stuck leads to the kind of questions Stack Overflow is best at.

Headers vs Libraries in C/C++

There is an important distinction to be made between header files and libraries in C++. Header files are the visible thing in your code, since they are what you actually mention in an #include statement. In most cases, though, the headers you are including correspond to libraries installed on the system.

As a practical matter this is important for two reasons:

1. You don't generally install "headers" on your system, you install libraries that happen to come with headers. There are a small number of header-only libraries that are exceptions to this rule, but usually you have a binary library somewhere that the header is facilitating access to.
2. The #include statement is only half of the story. There is usually a corresponding compiler option where you need to specify that you want to link against a particular library. In an IDE, this will be buried in the project options somewhere. For a command line compiler, this will be a switch that you pass to the compiler on the command line or (more commonly) in a Make file or similar.

That second point is actually true of your standard libraries like iostream or stdio.h , but these are backed by the standard C or C++ library that is linked in by default.

Linux in general

Most linux distributions will come with a package manager of some kind. There are a number available (Ubuntu uses Apt, Redhat uses yum, Arch has pacman, Gentoo has portage, etc.) The actual manager used is one of the defining properties of the distribution. Documentation will be easy to find on your Distro's web page. This is a very important tool to understand.

With the exception of the various C/C++ and Posix standard headers, the headers you have available for use are a function of the libraries you have installed on your system. This is important to understand because the list of available headers consists of all the available libraries on the internet, not just the few that your system happens to have installed at the moment.

Each library will generally be wrapped up as a package for your linux distro. When you locate a library that you want, you install the corresponding package. This will give you the required header and library files.

It actually isn't often useful to go looking for the libraries and headers on your hard drive, but if you are curious, header files conventionally end up somewhere in one of the following directories (or a subdirectory inside these)

    /usr/local/include
    /usr/include

Libraries will mostly be found in

    /lib
    /usr/lib
    /usr/local/lib

These will have cryptic names that include their version number, and a more general (still cryptic) name that symlinks to the one with the specific version number.

Some distributions have separate "development" versions of libraries that include the headers, and only install the runtime files by default (ie the files your users need to run your program). If your distro does this, you'll need the development package to write software with that library.

When you have decided on what functionality you require, you generally go looking for a library that will help you accomplish that task. You can ask around on forums, or just google for them.

Device drivers in the Kernel

Most libraries will interface with a device through a device driver. In linux, device drivers are compiled into the kernel, or present as modules that are loaded into the kernel. Your Pi distribution will hopefully have come with all the required drivers for the hardware present. If not, you'll need to obtain a kernel module or recompile your kernel to include the required driver. The modules and appropriate scripts to load/unload them are generally available as packages for your distro, just as libraries are.

It is possible to write software to talk to a driver directly. This is a VERY broad topic. Your best bet is to pick a device (ie I2C, SPI, etc) and google for a tutorial for interfacing with that device on the Pi specifically.

This tutorial addresses the basics of writing a loadable module. It would be a good place to start if you want to write your own SPI driver.

This is a good place to go for a general kernel overview. It will help you understand what is available, how to get a copy of the kernel source, etc. This is also good knowledge to have if you want to write a driver. It is also a place to learn how to get your code submitted to the kernel, if you develop something new.

Finally, writing your own device drivers is possible, and isn't something to be scared of. The details of this topic that could fill a book, though, so it is something to google when you are ready to try it.

Linux on the Raspberry Pi

The first thing to understand about the Pi is that it is in most ways no different from a PC running linux. Any general information you find about systems programming for linux on a PC will apply equally to the Pi. The only caveats are that the processor architecture is different (ARM, vs Intel/AMD), and the Pi has a few hardware items (like I2C, SPI and GPIO) that are not common, or at least not commonly interfaced with, on the PC.

There is actually more than one linux distribution available on the Pi. These are usually derived from common PC distributions -- Ubuntu derived distros are most common. You'll want to locate the website for whichever distro you have.

If you try to install things outside of your package manager, you'll need to be careful to get libraries compiled for the ARM processor (or source libraries that you compile yourself). There are a few exceptions, but the vast majority of open source libraries should be usable on ARM.

This looks like a promising library that might be a good starting point.

This looks like a good GPIO (General Purpose Input/Output -- ie, pins you can toggle) tutorial.

This leads to some some SPI sample code.