install_json_c.sh

Overview

install_json_c.sh is a Bash shell script designed to automate the process of downloading, building, and installing the json-c C library from its GitHub repository. It manages the environment setup, error handling, and installation path configuration to ensure a reliable and repeatable installation of the library into a specific project directory structure.

Script Breakdown and Functionality

1. Shell Environment Setup

#!/usr/bin/env bash
set -e
if [[ "${BASHOPTS}" != *extdebug* ]]; then
    set -e
fi

• The script starts with a shebang pointing to the user's environment Bash interpreter.

• set -e instructs the shell to exit immediately if any command exits with a non-zero status, enhancing robustness.

• The conditional re-application of set -e if the extdebug option is not enabled ensures consistent error handling behavior even in debugging environments.

2. Error Reporting Function: err_report

err_report() {
    cd ${source}
    echo "ERROR: $0:$*"
    exit 8
}

• Purpose: To provide a custom error message and exit the script when a command fails.

• Parameters: $* captures the line number or any additional information passed when invoked.

• Behavior:

  • Changes the working directory to the path stored in the variable source (note: source is not defined elsewhere in the script, which could cause issues if an error occurs before this is set).

  • Prints an error message indicating the script name ($0) and the error context.

  • Exits the script with exit code 8, signaling failure.

3. Error Trap Setup

if [[ "${BASHOPTS}" != *extdebug* ]]; then
    trap 'err_report $LINENO' ERR
fi

• Sets a trap to catch any command error (ERR signal).

• When an error occurs, it calls err_report with the line number of the failure ($LINENO).

• This aids in debugging by pinpointing exactly where the script failed.

• The trap is disabled if the extdebug option is enabled, allowing for standard debugging.

4. Directory and Build Setup

cwd=$(cd "$(dirname $(dirname "${BASH_SOURCE[0]}"))" &> /dev/null && pwd)
BUILD_DIR="${cwd}/build"

mkdir -p "$BUILD_DIR"
cd "$BUILD_DIR"

• cwd: The script calculates the root directory by navigating two levels up from the script's location (${BASH_SOURCE[0]}).

  • This assumes the script is located two directories below the project root.

• BUILD_DIR: Defines a build directory inside the project root.

• Creates the build directory if it doesn't exist and changes the current directory to it.

• This setup isolates build artifacts from source files.

5. Cloning and Building json-c

git clone https://github.com/json-c/json-c.git
cd json-c

cmake -DCMAKE_INSTALL_PREFIX=../../libs/ -DCMAKE_BUILD_TYPE=release
make all install

• Clones the official json-c GitHub repository into the build directory.

• Enters the cloned json-c directory.

• Runs CMake with two parameters:

  • CMAKE_INSTALL_PREFIX=../../libs/: Installs the library into the libs directory at the project root level.

  • CMAKE_BUILD_TYPE=release: Configures the build for a release version, optimizing performance.

• Executes make all install to build and install the library.

6. Finalization

cd "${cwd}"

[[ $SHLVL -eq 2 ]] && echo OK

cd "${pwd}"

• Returns to the project root directory.

• Checks if the shell level ($SHLVL) equals 2, indicating the script was run in a particular shell invocation context; if true, it outputs OK to signal successful completion.

• Attempts to change directory back to the original working directory stored in ${pwd}; however, ${pwd} is not explicitly set in the script, which might cause an error or unintended behavior.

Important Implementation Details

• Error Handling: The script employs set -e and an error trap to halt execution on failures and provide contextual error messages.

• Relative Paths: Uses relative paths based on the script's location to manage build and installation directories, ensuring portability within the project.

• Build Isolation: The build occurs in a dedicated build directory, keeping source and build files separate.

• Installation Prefix: Installs json-c into a libs folder inside the project, allowing the project to use the installed library without relying on system-wide installations.

Interaction with Other Parts of the System

• The script is intended to be executed from within the project directory tree.

• It depends on:

  • git being available to clone the repository.

  • cmake and make tools for building the library.

• The output installation directory (libs/) is likely referenced by the main project build system or runtime environment to link against the json-c library.

• The build directory (build/) is a transient workspace for compilation that does not affect source files.

• The script assumes the presence of Bash shell features and certain environment variables (BASHOPTS, BASH_SOURCE, SHLVL).

Usage Example

To use this script, navigate to the appropriate project directory and run:

./install_json_c.sh

Upon successful execution, the json-c library will be cloned, built, and installed into the libs/ directory relative to the project root.

Mermaid Diagram: Script Workflow

flowchart TD
Start --> Check_BashOpts
Check_BashOpts --> Setup_Error_Trap
Setup_Error_Trap --> Set_Directories
Set_Directories --> Create_Build_Dir
Create_Build_Dir --> Clone_Repo
Clone_Repo --> Enter_Repo
Enter_Repo --> Run_CMake
Run_CMake --> Make_Install
Make_Install --> Return_To_Root
Return_To_Root --> Check_SHLVL
Check_SHLVL --> End
subgraph ErrorHandling
Check_BashOpts
Setup_Error_Trap
end
subgraph BuildSetup
Set_Directories
Create_Build_Dir
end
subgraph BuildAndInstall
Clone_Repo
Enter_Repo
Run_CMake
Make_Install
end
subgraph Finalization
Return_To_Root
Check_SHLVL
end

This documentation provides a detailed understanding of the install_json_c.sh script, enabling effective use and modification in the context of its project.