ChildProcess C++ library

v1.0.6

Table of contents

• Overview
• Versions
• Library files
• ChildProcess class description
  • ChildProcess class declaration
  • getVersion method
  • run method
  • close method
• Build and connect to your project
• Example

Overview

ChildProcess C++ library provides an interface to run external processes from your application in Linux. The library runs an external process (child process) and returns control to you. The library doesn’t show the child process output, it just runs. The library also provides a function to stop the child process (the process will be terminated automatically in the ChildProcess class destructor). The library doesn’t have third-party dependencies and is built with the C++17 standard.

Versions

Table 1 - Library versions.

Version	Release date	What’s new
1.0.0	16.08.2023	- First version
1.0.1	16.01.2024	- Examples updated. - Documentation updated.
1.0.2	16.04.2024	- Documentation updated.
1.0.3	17.05.2024	- Documentation updated.
1.0.4	17.07.2024	- CMake updated.
1.0.5	04.12.2024	- Fix process kill procedure.
1.0.6	04.12.2024	- Fix close method.

Library files

The library is supplied only by source code. The user is given a set of files in the form of a CMake project (repository). The repository structure is shown below:

CMakeLists.txt ---------------- Main CMake file of the library.
src --------------------------- Folder with library source code.
    ChildProcess.cpp ---------- C++ implementation file.
    ChildProcess.h ------------ Library main header file.
    ChildProcessVersion.h ----- Header file with library version.
    ChildProcessVersion.h.in -- CMake service file to generate version header.
example ----------------------- Folder of example application.
    CMakeLists.txt ------------ CMake file of example application.
    main.cpp ------------------ Source C++ file of example application.

ChildProcess class description

ChildProcess class declaration

ChildProcess class declared in ChildProcess.h file. Class declaration:

namespace cr
{
namespace utils
{
/// Child process class.
class ChildProcess
{
public:

    /// Get library version.
    static std::string getVersion();

    /// Class constructor.
    ChildProcess();

    /// Class destructor.
    ~ChildProcess();

    /// Create a child process and run given command with provided arguments.
    bool run(std::string command, std::string params = "");

    /// Close child process.
    void close();
};
}
}

getVersion method

The getVersion() method returns string of current version of ChildProcess class. Method declaration:

static std::string getVersion();

Method can be used without ChildProcess class instance:

cout << "ChildProcess class version: " << ChildProcess::getVersion();

Console output:

ChildProcess class version: 1.0.6

run method

The run() method runs the given command with provided arguments under a new process. The command and params are concatenated with a space and then parsed into separate arguments for execution. Method declaration:

bool run(std::string command, std::string params = "");

Parameter	Value
command	Command/program to run (for example: mkdir or myProgram etc).
params	Optional arguments for command (for example: -l, newDirectory or myProgramInput.txt etc). These will be concatenated with the command and parsed as separate arguments.

Returns: TRUE if the command starts successfully in a new process or FALSE if not.

close method

The close() method terminates the created child process. When the library runs a child process, the library remembers the PID of the child process. The method first attempts to gracefully terminate the process using SIGTERM, and if the process doesn’t respond, it forces termination with SIGKILL. Method declaration:

void close();

Build and connect to your project

Typical commands to build ChildProcess library:

cd ChildProcess
mkdir build
cd build
cmake ..
make

If you want to connect ChildProcess library to your CMake project as source code you can do the following. For example, if your repository has structure:

CMakeLists.txt
src
    CMakeList.txt
    yourLib.h
    yourLib.cpp

Create 3rdparty folder in your repository and copy ChildProcess repository folder there. The new structure of your repository:

CMakeLists.txt
src
    CMakeList.txt
    yourLib.h
    yourLib.cpp
3rdparty
    ChildProcess

Create a CMakeLists.txt file in the 3rdparty folder. CMakeLists.txt should contain:

cmake_minimum_required(VERSION 3.13)

################################################################################
## 3RD-PARTY
## dependencies for the project
################################################################################
project(3rdparty LANGUAGES CXX)

################################################################################
## SETTINGS
## basic 3rd-party settings before use
################################################################################
# To inherit the top-level architecture when the project is used as a submodule.
SET(PARENT ${PARENT}_YOUR_PROJECT_3RDPARTY)
# Disable self-overwriting of parameters inside included subdirectories.
SET(${PARENT}_SUBMODULE_CACHE_OVERWRITE OFF CACHE BOOL "" FORCE)

################################################################################
## CONFIGURATION
## 3rd-party submodules configuration
################################################################################
SET(${PARENT}_SUBMODULE_CHILD_PROCESS                   ON  CACHE BOOL "" FORCE)
if (${PARENT}_SUBMODULE_CHILD_PROCESS)
    SET(${PARENT}_CHILD_PROCESS                         ON  CACHE BOOL "" FORCE)
    SET(${PARENT}_CHILD_PROCESS_EXAMPLE                 OFF CACHE BOOL "" FORCE)
endif()

################################################################################
## INCLUDING SUBDIRECTORIES
## Adding subdirectories according to the 3rd-party configuration
################################################################################
if (${PARENT}_SUBMODULE_CHILD_PROCESS)
    add_subdirectory(ChildProcess)
endif()

File 3rdparty/CMakeLists.txt adds the ChildProcess folder to your project and excludes the example application from compiling (by default, test applications and examples are excluded from compiling if ChildProcess is included as a sub-repository). The new structure of the repository:

CMakeLists.txt
src
    CMakeList.txt
    yourLib.h
    yourLib.cpp
3rdparty
    CMakeLists.txt
    ChildProcess

Next you need to include the 3rdparty folder in the main CMakeLists.txt file of your repository. Add this line at the end of your main CMakeLists.txt:

add_subdirectory(3rdparty)

Next you have to include ChildProcess library in your src/CMakeLists.txt file:

target_link_libraries(${PROJECT_NAME} ChildProcess)

Done!

Example

Example application runs given command with arguments and after 2 seconds stops child process.

#include <iostream>
#include <string>
#include <chrono>
#include <thread>
#include "ChildProcess.h"

int main(void)
{
    std::cout << "ChildProcess v" <<
    cr::utils::ChildProcess::getVersion() << " example" <<
    std::endl << std::endl;

    std::string command = "";
    std::cout << "Enter command: ";
    std::cin >> command;

    std::string arguments = "";
    std::cout << "Enter arguments: ";
    std::cin >> arguments;

    // Run child process.
    cr::utils::ChildProcess process;
    if (!process.run(command, arguments))
        return -1;

    // Wait 2 seconds for example.
    std::this_thread::sleep_for(std::chrono::seconds(2));

    // Close child process.
    process.close();

    return 0;
}

---

Table of contents