igraph tutorial update

This is a draft update to the first lesson in the tutorial, igraph Reference Manual

It will apply to the future version 0.9.2. Those trying it now should install igraph from the master branch on GitHub.

Lesson 1. Compiling programs using igraph

Your first igraph program

The following short example program demonstrates the basic usage of the igraph library.

/* igraph_test.c */

#include <igraph.h>

int main() {
  igraph_real_t diameter;
  igraph_t graph;

  igraph_rng_seed(igraph_rng_default(), 42);

  igraph_erdos_renyi_game(&graph, IGRAPH_ERDOS_RENYI_GNM, 1000, 3000,
                          IGRAPH_UNDIRECTED, IGRAPH_NO_LOOPS);

  igraph_diameter(&graph, &diameter, 0, 0, 0, IGRAPH_UNDIRECTED, 1);
  printf("Diameter of a random graph with average degree %g: %g\n",
          2.0 * igraph_ecount(&graph) / igraph_vcount(&graph), 
          (double) diameter);

  igraph_destroy(&graph);

  return 0;
}

This example illustrates a couple of points. First, programs using the igraph library should include the igraph.h header file. Second, igraph uses the igraph_real_t type for real numbers instead of double. Third, igraph graph objects are represented by the igraph_t data type. Fourth, the igraph_erdos_renyi_game() creates a graph and igraph_destroy() destroys it, i.e. deallocates the memory associated to it.

To compile this program, you need a C compiler. Optionally, CMake can be used to automate the compilation.

Compiling with CMake

It is convenient to use CMake because it can automatically discover the necessary compilation flags on all operating systems. Many IDEs support CMake, and can work with CMake projects directly. To create a CMake project for this example program, create a file name CMakeLists.txt with the following contents:

cmake_minimum_required(VERSION 3.16)
project(igraph_test C)

find_package(igraph REQUIRED)

add_executable(igraph_test igraph_test.c)
target_link_libraries(igraph_test PUBLIC igraph::igraph)

To compile the project, create a new directory called build, and switch to it:

mkdir build && cd build

Run CMake to configure the project:

cmake ..

If igraph was installed at a non-standard location, specify its prefix using the -DCMAKE_PREFIX_PATH=... option. The prefix must be the same directory that was specified as the CMAKE_INSTALL_PREFIX when compiling igraph.

If configuration has succeeded, build the program using

cmake --build .

Compiling without CMake

On most Unix-like systems, the default C compiler is called cc. To compile the test program, you will need a command similar to the following:

cc igraph_test.c -I/usr/local/include/igraph -L/usr/local/lib -ligraph -o igraph_test

The exact form depends on where igraph was installed on your system, whether it was compiled as a shared or static library, and the external libraries it was linked to. The directory after the -I switch is the one containing the igraph.h file, while the one following -L should contain the library file itself, usually a file called libigraph.a (static library on Linux or macOS), libigraph.so (shared library on Linux), libigraph.dylib (shared library macOS), igraph.lib (static library on Windows) or igraph.dll (shared library on Windows). If igraph was compiled as a static library, it is also necessary to manually link to all of its dependencies.

If your system has the pkg-config utility you are likely to get the necessary compile options by issuing the command pkg-config --libs --cflags igraph (if igraph was built as a shared library) or pkg-config --static --libs --cfgals igraph (if igraph was built as a static library).

Running the program

On most systems, the executable can be run by simply typing its name like this:

./igraph_test

If you use dynamic linking and the igraph library is not in a standard place, you may need to add its location to the LD_LIBRARY_PATH (Linux), DYLD_LIBRARY_PATH (macOS) or PATH (Windows) environment variables.

Revision 3 was converted to DocBook and committed to the repo.