Some aspects of Ignition Fuel Tools can be configured according to the needs of the library users. This configuration can be done via a YAML configuration file or programatically.
Ignition Fuel Tools accepts a YAML file with the following syntax:
servers section specifies all Fuel servers to interact with. For each server, you can specify a name and the URL to send the HTTP requests. You're not allowed to have multiple servers with the same name. Also,
url are required fields when enabling a server.
cache section captures options related with the local storage of the assets.
path specifies the local directory where all assets will be downloaded. If not used, all assets are stored under
Once the configuration file is ready you need to tell an instance of the
ClientConfig class how to find it. But let's do it with an example.
Create a file
/tmp/my_config.yaml with the following content:
Now, let's use a program that downloads a model from a server in the configuration file. Let's start by creating a directory for storing all files:
Download the file
modelDownload.cc and save it under
CMakeLists.txt for compiling the example:
Let's compile the example:
And now the fun part, execute it:
Verify that you have the model in
/tmp/ignition/fuel/models/, as you configured in your YAML file.
Let's jump to the interesting parts of the program:
In the previous block, we can see how a
ClientConfig is instantiated. This class lets you specify different options to be customized by the client using the library.
Next, we check if the
-s (server) has been used when invoking our program. If that's the case, we instantiate an object of
ServerConfig and we fill the URL with the value of the
-s flag. Notice that the
localname of the server is hard-coded to
ignitionfuel to simplify the program. Next, we use
AddServer() to register the new server. The previous block shows an example of a programmatic way of configuring a Fuel server. Let's focus on the next interesting piece of code:
Here, we check if the user specified a
-c (config) option. If so, we need to tell
conf about the path where the configuration file is located. For this purpose we use
SetConfigPath(). As we're interested in using a configuration file, we need to call
LoadConfig(). It's important to note that if we call
LoadConfig() without calling
SetConfigPath() before, a default configuration file will be loaded (and created if it doesn't exist already under
$HOME/.ignition/fuel/config.yaml). If the user doesn't call
LoadConfig(), no configuration file will be used at all.
Once we have all our configuration ready and captured in the
conf object, we can instantiate the
FuelClient object (client). This is the class that performs the main operations, such as the model download described in this example.
The code above sets the owner and name of the requested model. Finally, it iterates over all available Fuel servers and tries to download the model.