Utility programs

Table of Contents

• Discussion
• Crosscompiling
• BinaryBuilder
  • Command-line usage
    • Help
    • Output directory
    • File base name
    • Namespace
    • Input files
  • The C++ side
  • CMake integration
    • limes_add_binary_data_files
    • limes_add_binary_data_target
• FileUtil
  • Usage
    • absolute
    • append
    • cat
    • cd
    • copy
    • equiv
    • exists
    • follow_symlink
    • glob
    • hash
    • ln
    • ls
    • mkdir
    • modtime
    • native
    • path
    • prepend
    • pwd
    • relative
    • rename
    • rm
    • sep
    • size
    • space
    • touch
    • type
    • which
    • write

Discussion

Limes ships several small command-line utility programs, both as part of the testing process of the Limes libraries, but also because these utility programs can be genuinely useful.

Limes ships the following programs:

Name	Description
FileUtil	OS-agnostic interface for a wide variety of filesystem tasks
BinaryBuilder	Generates C++ source files which embed binary data files

Crosscompiling

When building the Limes programs in a crosscompiling scenario, they usually need to be executed on the host system, not the target system.

Because of this, when crosscompiling, a child CMake is invoked at configure time to execute the build of the programs for the host system, so that their artefacts are then available to the configuration for the target system.

BinaryBuilder

BinaryBuilder is a small command-line program that generates C++ source code that embeds some external data read from input files. The output files use the Limes binaries::FileInfo and binaries::FileInfoList interface for easy access of your embedded data at runtime.

Command-line usage

BinaryBuilder [-h] [-d <outputDirectory>] [-o <fileBaseName>] [-ns <namespace>] <inputFiles...>

All arguments are optional, except the <inputFiles> .

Help

BinaryBuilder -h

Prints usage and help messages.

Output directory

BinaryBuilder -d <outputDirectory> <inputFiles...>

The directory where the output files will be written to. No matter how many input files you pass, a single .cpp and .h file will be generated, containing all the data. These files will be at <outputDirectory>/<fileBaseName>.h and <outputDirectory>/<fileBaseName>.cpp . <outputDirectory> defaults to the current working directory.

File base name

BinaryBuilder -o <fileBaseName> <inputFiles...>

The base name used for naming the output files. The output files will be <outputDirectory>/<fileBaseName>.h and <outputDirectory>/<fileBaseName>.cpp . <fileBaseName> defaults to BinaryData .

Namespace

BinaryBuilder -ns <namespace> <inputFiles...>

The namespace that the embedded data objects will be declared in. This may be empty, and defaults to empty.

Input files

BinaryBuilder <inputFiles...>

The paths of files to be embedded as binary data into the generated source files. If a directory is given, its contents will all be included recursively.

The C++ side

After the BinaryBuilder executable has run, you'll have a .cpp and .h file, and the header file will contain some code like this:

#pragma once
 
#include <limes_core.h>
 
extern const std::size_t fileInfoListSize;
 
extern const ::limes::binaries::FileInfo fileInfoList[];
 
[[nodiscard]] constexpr ::limes::binaries::FileInfoList fileList() noexcept
{
    return ::limes::binaries::FileInfoList { &fileInfoList[0], fileInfoListSize };
}

The static array of FileInfo objects is initialized in the .cpp file. This header gives you direct access to an iterable array of FileInfo objects, which provide a convenient API for loading your embedded data into familiar C++ objects.

CMake integration

Limes also provides a CMake module, LimesBinaryBuilder.cmake , that provides several utility functions for adding file generation commands to a target:

limes_add_binary_data_files

Usage:

limes_add_binary_data_files (INPUTS <files...>
                            [OUTPUT_DIR <dir>]
                            [BASE_NAME <filename>]
                            [NAMESPACE <namespace>]
                            [CPP_OUTPUT_VAR <cpp_path_out>]
                            [H_OUTPUT_VAR <h_path_out>])

limes_add_binary_data_target

Usage:

limes_add_binary_data_target (TARGET_NAME <target>
                              INPUTS <files...>
                             [HEADER_NAME <header>]
                             [NAMESPACE <namespace>]
                             [INSTALL_REL_PATH <rel_path>]
                             [INSTALL_COMPONENT <component>])

FileUtil

FileUtil is a small command-line program that provides an OS-agnostic interface to common filesystem operations, including emulation of most Unix filesystem commands.

Usage

FileUtil <mode> [<args...>]

where <mode> is one one:

absolute

Convert an input path to an absolute path.

FileUtil absolute <path> [<basePath>]

If <path> is an absolute path, prints <path> ; otherwise, prints <basePath>/<path> . If <basePath> is not specified, it defaults to the current working directory.

append

Append content to a given file.

FileUtil append <filename> <content> [--strict]

Note that the content is given as a single argument. If the file did not already exist, then an error will be raised if the –strict option was given; otherwise, the content will be written to the file as if the write command were called.

cat

Concatenate and display contents of the given files.

FileUtil cat <filenames...> [--output <outputFile>]

If <outputFile> is specified, the concatenated output will be written to that file; otherwise, output is printed to the standard output.

cd

Change the current working directory.

FileUtil cd <directory>

copy

Copy files and directories to a new location.

FileUtil copy <filesOrDirs...> <destination>

In this command, the last argument is always the destination. If one input file is given, the destination may be a filename. If multiple inputs are given, the destination must be a directory. If the destination is a directory that doesn't exist, it will be created.

equiv

Check if two paths are equivalent.

FileUtil equiv <path1> <path2> [--error]

Prints yes if the two paths refer to the same filesystem object; otherwise, prints no . If the –error option is given, the result of the comparison is indicated by an exit code of 0 or 1 instead of printing to standard output.

exists

Check if files and/or directories exist.

FileUtil exists <filesOrDirs...> [--error]

Prints yes if every item in the passed list exists; otherwise prints no . If the –error option is given, the result of the comparison is indicated by an exit code of 0 or 1 instead of printing to standard output.

follow_symlink

Print the target of a symbolic link.

FileUtil follow_symlink <symlink> [--no-recurse]

This command follows the given symlink (and, if it points to another symlink, follows that symlink, etc), and prints the absolute path of the target to the standard output. If the optional –no-recurse argument is present, then the recursive behavior is disabled, and the path of the passed symlink is printed, even if its target is another symlink.

glob

Find files/directories matching a pattern.

FileUtil glob <globbingExpression> [--dir <baseDir>] [--recurse] [--error]

Prints a list of absolute paths found that match the given globbing expression. If the <baseDir> option is given, files will be searched for in that directory. Otherwise, it defaults to the current working directory. If the –error flag is given, the program will exit with an error code if no files are found. Otherwise, 'No files found' will be printed.

hash

Compute a hash of a file's contents.

FileUtil hash <hashType> <filename>

Prints a crypographic hash of a file's contents to standard output. Available hash types are: md5 , sha1 , sha224 , sha256 , sha384 , and sha512 .

ln

Create a symbolic link.

FileUtil ln <symLinkPath> <symLinkTarget>

ls

List directory contents.

FileUtil ls [<directory>]

The additional <directory> argument is optional; if omitted, this command lists the contents of the current working directory.

mkdir

Create a directory.

FileUtil mkdir <directory>

modtime

Display the last modification time of a file or directory.

FileUtil modtime <fileOrDirectory>

This command prints the last modification time of the file or directory to standard output in the form HH:MM:SS Day Month Year, with the time in 24-hour format and the month as a 3-letter abbreviation; for example, 03:33:52 2 May 2022.

native

Convert a path to the current platform's preferred directory separators.

FileUtil native <path>

Converts any directory separators in <path> to the preferred directory separator for the current platform. Unlike most other commands, this one does not make the passed path absolute if a relative path was given.

path

Prints the contents of the PATH environment variable.

FileUtil path

Prints the contents of the PATH environment variable as a list of absolute paths to directories, one per line of output.

prepend

Prepend content to a file.

FileUtil prepend <filename> <content> [--strict]

Note that the content is given as a single argument. If the file did not already exist, then an error will be raised if the –strict option was given; otherwise, the content will be written to the file as if the write command were called.

pwd

Print the absolute path of the current working directory

FileUtil pwd

relative

Get a path relative to another location.

FileUtil relative <path> [<basePath>]

If <basePath> is not specified, it defaults to the current working directory.

rename

Rename a file or directory.

FileUtil rename <oldName> <newName>

rm

Remove files and/or directories.

FileUtil rm <filesOrDirs...>

sep

Prints the current platform's preferred directory separator.

FileUtil sep

size

Prints the size of a file or directory, in bytes.

FileUtil size [<fileOrDir>]

The size is printed to standard output and is represented as bytes. If a directory is passed, this command reports the cumulative size of all the directory's contents. If no file or directory is specified, this command prints the capacity of the entire filesystem.

space

Prints the amount of remaining space on the filesystem, in bytes

FileUtil space

touch

Update modification time of files or directories

FileUtil touch <filesOrDirs...> [--no-create]

If the –no-create option is specified, files/directories in the input list that don't already exist will simply be ignored. Otherwise, they will be created.

type

Print the type of a filesystem entry

FileUtil type <path>

If nothing exists at <path> , raise an error. Otherwise, prints one of file , directory , or symlink describing what exists at the given path.

which

Locate an executable.

FileUtil which [<programName>]

Searches for an executable file named <programName> in each of the directories in the PATH environment variable and prints the absolute path of the first match found. If the <programName> is omitted, this command prints the path of the currently running FileUtil executable itself.

write

Write content to a file.

FileUtil write <filename> <content> [--no-overwrite]

Note that the content is given as a single argument. If the –no-overwrite option is given, then an error is raised if the file already existed; otherwise, it will be overwritten.