qi::path Developer Guide

go to the qi::path API reference.

Overview

The SDK Layout

The main idea of the qibuild-based project is that you always end up with the same layout.

For instance, right after having built you project, you end up with a directory looking like this:

Here we assume you have a foo executable which:

• depends on a bar dynamic library
• need to read data from a file named foo.data
• need to read configuration from a file named foo.cfg

src
|__ foo
    |__ data
        |___ foo.data
    |__ etc
        |__ foo.cfg

build
|___
    sdk
    |__ lib
         |___ libbar.so
    |__ bin
         |__ foo

When everything is installed, you have something like:

prefix
  |__ lib
      |__ libbar.so
  |__ bin
      |__ foo
  |__ share
      |__ foo
          |__ foo.data
  |__ etc
      |__ foo
          |__ foo.cfg

The problem

Here is a list of common requirements:

• Find the files foo/foo.cfg, foo/foo.data in a clean, simple way, while making sure the solution works whereas the project is built or installed

• The executable foo may need to write or update its configuration files or data but we need to make sure nothing will be written inside the installed directory

• Since there will be several foo.cfg files, we need to be able to process then in a correct order.

The solution

Here is how it works:

• First we introduce the concept of prefix. When something is built, the prefix is /path/to/build/sdk, when something is installed, the prefix is the DESTDIR plus the installation prefix.

• Then we make sure the layout in the build prefix and in the install prefix is always the same. For instance, we will have CMake rules to be sure that whenever the foo project is configured, a copy of foo.cfg is placed in build/sdk/foo/foo.cfg (same thing for data)

  • At last, we provide an easy way to get the prefix anywhere from the c++ code. The idea is that it is easy to get the prefix from argv0. For instance, if argv0 is /path/to/build/sdk/bin/foo, we can assume the prefix is /path/to/build/sdk.

Link

qi::path documentation.

Using Namespace path

Notes & Requirement

The API of qi::path always make sure that:

• returned path are absolute, native paths. (with "/" on UNIX and "\" on windows)
• path always MUST be in UTF-8 encoding (every methods who need UTF-8 charset is specified in qi::path "API of qi::path"),
• return path will be in UTF-8 charset.

For this to work, we must make sure that

• qi::init has been called.

Have a look on the API of qi::path for more details

Reading and writing configuration files

Writing a configuration file is very different from reading one.

Let's assume the foo executable want to make sure that SPAM=42 in foo.cfg.

Here is how it works:

• First, ask for a list of possible paths for foo.cfg

• Iterate through this list and stop when the first possible foo.cfg is found

• Read and update the foo.cfg file

• Write the foo.cfg file.

You can see that we ask for a list of paths when reading, but that we always write to one file.

Let's go through these steps again, assuming foo is installed in /usr/bin/foo, and foo.cfg in /usr/share/foo/foo.cfg, and that there is nothing else on the machine where foo is running.

• First step: ask for a list of possible paths for foo.cfg using qi::path::getConfigurationPaths
  This gives a list looking like :
  [~/.config/foo/foo.cfg, /usr/share/foo/foo.cfg]

• Since .config/foo/foo.cfg does not exist, we read /usr/share/foo/foo.cfg

• Then we ask for a location to write: using qi::path::getConfigurationPaths
  In this case it's ~/.config/foo/foo.cfg
  So we write SPAM=42 to ~/.config/foo/foo.cfg

Then each time a piece of code will ask for the foo.cfg path, it will get a list starting with ~/.config/foo/foo.cfg, so we are sure the setting SPAM=42 will be used.

Example

/*
 * Copyright (c) 2012 Aldebaran Robotics. All rights reserved.
 * Use of this source code is governed by a BSD-style license that can be
 * found in the COPYING file.
 */
#include <iostream>
#include <fstream>
#include <vector>

#include <qi/os.hpp>
#include <qi/path.hpp>
#include <qi/qi.hpp>

#include <boost/locale.hpp>
#include <boost/filesystem.hpp>
#include <locale>

int main(int argc, char *argv[])
{
  // Set the global locale to loc
  std::locale::global(boost::locale::generator().generate(""));
  // Make boost.filesystem use it
  boost::filesystem::path::imbue(std::locale());

  // Get the prefix name from argv0
  std::cout << "argv0 is: " << argv[0] << std::endl;
  // Get the prefix name from argv0
  // Performs various initializations.
  // This is usually called by qi::init()
  qi::init(argc, argv);

  // Get sdk prefix
  std::cout << "SDK prefix is: " << qi::path::sdkPrefix() << std::endl;

  // First argument is the name of the application, used
  // to build various paths later.
  std::string fooCfgPath = qi::path::findConf("foo", "foo.cfg");
  if (fooCfgPath == "")
  {
    std::cerr << "Could not find foo.cfg" << std::endl;
    std::cerr << "Looked in: " << std::endl;
    std::vector<std::string > configPaths = qi::path::confPaths("foo");
    std::vector<std::string>::const_iterator it;
    for (it = configPaths.begin(); it != configPaths.end(); ++it)
    {
      std::cerr << "\t" << *it << std::endl;
    }
  }
  else
  {
    std::cout << "Found foo.cfg: " << fooCfgPath << std::endl;
    std::cout << "Contents: " << std::endl;
    char buf[250];
    std::ifstream ifs;

    // Set stream to the right charset
    ifs.imbue(std::locale());
    ifs.open(fooCfgPath.c_str(), std::fstream::in);
    while (! ifs.eof())
    {
      ifs.getline(buf, 250);
      std::cout << buf << std::endl;
    }
    ifs.close();
  }


  // ... Write back the configuration to userCfgPath
  std::string userCfgPath = qi::path::userWritableConfPath("foo", "foo.cfg");
  std::cout << "Writing config file to: " << userCfgPath << std::endl;
  std::ofstream ofs(userCfgPath.c_str(), std::fstream::out | std::fstream::trunc);
  ofs << "Hi, this is foo.cfg" << std::endl;
  ofs.close();

  return 0;
}

Link

qi::path documentation.