Introduction of Argtable3

Argtable3 is an open-source ANSI C library that simplifies parsing GNU-style command-line options. It provides a declarative API to define your command-line syntax, and because it's built on the standard getopt library, it ensures 100% GNU-compliant behavior. Argtable3 automatically generates the error-handling logic and usage descriptions that are essential for any robust command-line program, saving you from tedious boilerplate code.

Quick Start

There are several ways to use Argtable3 in your C/C++ projects:

• Embed Amalgamation Source Files: Download the amalgamation package and include argtable3.c and argtable3.h in your project. This is the simplest and recommended approach.

• Use vcpkg: Add Argtable3 as a dependency in your project's vcpkg manifest for single-project use, or install it globally with vcpkg for system-wide access.

• Use Meson WrapDB: Integrate Argtable3 into Meson-based projects using the Meson WrapDB.

• Use Conan: Add Argtable3 as a dependency in your Conanfile for projects using Conan package management.

• Build from Source: Download release archives or clone the repository to build Argtable3 manually. This is ideal for contributors or those needing custom features.

Embed Amalgamation Source Files

Download the amalgamation package from the release page and add argtable3.c and argtable3.h to your project. This approach is the simplest and recommended way to use Argtable3, as it eliminates the need to build the library and enables better inter-procedural optimization by the compiler.

Use vcpkg for a Single Project

vcpkg is an open source C/C++ package manager based on CMake, and it supports the latest releases of Argtable3. To add the library to your CMake project, it's recommended to add vcpkg as a submodule to your project repo and use it to manage project dependencies. All libraries installed in this way can only be consumed by the project and won't impact other projects in the system.

If your project is under D:/projects/demo and the vcpkg submodule is under D:/projects/demo/deps/vcpkg, first you need to add Argtable3 to the manifest, D:/projects/demo/vcpkg.json:

{
    "name": "demo",
    "version": "0.0.1",
    "dependencies": [
        {
            "name": "argtable3",
            "version>=": "3.2.1"
        }
    ],
    "builtin-baseline": "92b42c4c680defe94f1665a847d04ded890f372e"
}

To add Argtable3 to your CMake scripts, you need to integrate the local vcpkg to CMake by setting the CMAKE_TOOLCHAIN_FILE variable. You also need to link to the static VC runtime (/MT or /MTd) if you want to use the static library version of Argtable3:

cmake_minimum_required(VERSION 3.18)

set(CMAKE_TOOLCHAIN_FILE ${CMAKE_CURRENT_SOURCE_DIR}/deps/vcpkg/scripts/buildsystems/vcpkg.cmake
  CACHE STRING "Vcpkg toolchain file")

project(versionstest)

add_executable(main main.cpp)

find_package(Argtable3 CONFIG REQUIRED)
target_link_libraries(main PRIVATE argtable3::argtable3)

if(VCPKG_TARGET_TRIPLET STREQUAL "x64-windows-static")
  set_property(TARGET main PROPERTY MSVC_RUNTIME_LIBRARY "MultiThreaded$<$<CONFIG:Debug>:Debug>")
endif()

Now you can run cmake to install Argtable3, configure and generate build scripts, and build the project:

$ mkdir build
$ cd build
$ cmake .. -DVCPKG_TARGET_TRIPLET=x64-windows-static
$ cmake --build .

Use vcpkg for All Projects

If you want to make Argtable3 available for all projects in the system, you can clone vcpkg to any directory and install packages there. Assuming vcpkg has been cloned in D:/dev/vcpkg and the directory has been added to PATH, you can install the static library version of Argtable3 in D:/dev/vcpkg/installed:

$ vcpkg install argtable3:x64-windows-static

Since each developer may clone vcpkg in a different place, it may not be appropriate to specify the CMAKE_TOOLCHAIN_FILE variable in CMakeLists.txt. Therefore, you should remove setting the CMAKE_TOOLCHAIN_FILE variable in the CMakeLists.txt example above, and set the variable in the command line:

$ mkdir build
$ cd build
$ cmake .. -DVCPKG_TARGET_TRIPLET=x64-windows-static -DCMAKE_TOOLCHAIN_FILE=D:/dev/vcpkg/scripts/buildsystems/vcpkg.cmake
$ cmake --build .

Use Meson WrapDB

If you are using Meson as your build system, you can use the Meson WrapDB to add Argtable3 as a dependency. This allows Meson to manage downloading and building Argtable3 automatically.

First, add the Argtable3 wrap file to your project's subprojects directory by running the following command in your project root:

$ meson wrap install argtable3

Next, declare the dependency in your meson.build file. Meson will automatically find the subproject.

# meson.build
project('demo', 'c', version: '0.0.1')

# Find the argtable3 dependency. Meson will find it in the subprojects
# directory via the .wrap file.
argtable3_dep = dependency('argtable3', version: '>=3.3.1')

executable(
  'main',
  'main.c',
  dependencies: [argtable3_dep]
)

Now you can configure and build your project, and Meson will handle the Argtable3 dependency:

meson setup build
meson compile -C build

Use Conan

If you are using Conan as your package manager, you can add Argtable3 as a dependency. Argtable3 is available on the Conan Center Index.

First, create a conanfile.txt in your project root with the following content. This will use the modern CMakeDeps and CMakeToolchain generators.

[requires]
argtable3/3.3.1

[generators]
CMakeDeps
CMakeToolchain

Next, install the dependencies from your project root. This command will download the package and generate the necessary CMake integration files in the build directory.

conan install . --output-folder=build --build=missing -s build_type=Release

Now, you can use find_package in your CMakeLists.txt to find and link against Argtable3.

# CMakeLists.txt
cmake_minimum_required(VERSION 3.15)
project(demo C)

# Find the package configuration files generated by Conan
find_package(Argtable3 REQUIRED)

add_executable(main main.c)

# Link the imported target provided by Conan
target_link_libraries(main PRIVATE argtable3::argtable3)

Finally, configure and build your project, making sure to point CMake to the toolchain file generated by Conan.

# From your project root
cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=build/conan_toolchain.cmake -DCMAKE_BUILD_TYPE=Release
cmake --build build

Build from Release Archives or Source

If none of the methods above suits your needs, or if you want to help developing Argtable3, you can always build from archives on the release page or from the repository.

$ cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
$ cmake --build build --config Debug
$ ctest --test-dir build -C Debug

Makefile-based generators in CMake only support one configuration at a time, so you need to specify CMAKE_BUILD_TYPE to Debug, Release, MinSizeRel, or RelWithDebInfo. To build multiple configurations, you need to create a build directory for each configuration.

Since v3.2.1, CMake scripts will check BUILD_SHARED_LIBS and build either the static library or the dynamic library at a time. BUILD_SHARED_LIBS is OFF by default, so if you want to build the dynamic library, you have to set BUILD_SHARED_LIBS to ON explicitly:

$ cmake -DCMAKE_BUILD_TYPE=Debug -DBUILD_SHARED_LIBS=ON ..

To cleanup, run make clean or remove the build directory:

$ rm -rf build

To build a tagged version, go to the project root directory, and use the Makefile in the project root to check out the specified tag:

$ make taglist
Available TAGs:
...
v3.3.1
...
$ make co TAG=v3.3.1
$ cd .archive/argtable-v3.3.1
$ cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
$ cmake --build build --config Debug
$ ctest --test-dir build -C Debug

Documentation

To learn how to use the Argtable3 API:

• Visit the official documentation.
• Explore examples in the examples directory.
• Review unit tests in the tests directory.

To build a local copy of the documentation, make sure you have installed Docker and run the following command in the repository root. The generated HTML files will be located in the docs/build/html directory.

$ make docs

Authors

Argtable is Copyright (C) 1998-2001,2003-2011 Stewart Heitmann. Parts are Copyright (C) 1989-1994, 1996-1999, 2001, 2003 Free Software Foundation, Inc.

Argtable was written by Stewart Heitmann [email protected]

Argtable is now maintained by Tom G. Huang [email protected] The project homepage of Argtable3 is https://www.argtable.org The project homepage of argtable2 is https://argtable.sourceforge.io

Here is a list of contributors who have helped to improve argtable:

• Nina Clemson: Editing the original argtable-1.0 documentation.
• Livio Bertacco: For bug fixes and the argtable-2.x Visual C++ Makefiles.
• Justin Dearing: For bug fixes and Windows DLL support, plus code support for the Open Watcom compiler and help with the Mac OS X configuration.
• Asa Packer: Contributing bug fixes and upgrades to the Visual C++ Makefiles.
• Danilo Cicerone: For the Italian translation of "Introduction to Argtable-2x" on http://www.digitazero.org.
• Uli Fouquet: For configuration patches and documentation related to cross-compiling argtable from Unix to Windows, as well as providing the arg_print_glossary_gnu function.
• Shachar Shemesh: For Debian package integration and kick-starting the migration to automake/autoconf.
• Jasper Lievisse Adriaanse: Maintaining the argtable package in OpenBSD ports.
• Ulrich Mohr: For bug fixes relating to Texas Instrument DSP platforms.
• John Vickers: For bug fixes relating to Solaris/Motorola platforms.
• Steve O'Neil: For bug fixes relating to Solaris/Motorola platforms.
• Lori A. Pritchett-Sheats: Fixing a makefile bug relating to "make dist".
• Paolo Bormida: For instructions on building argtable with date and regex support on Windows.
• Michel Valin: For bug fixes relating to the configure scripts on IBM AIX platforms and instructions on compiling the example code under AIX.
• Steve Christensen: Providing prebuilt packages for SPARC/Solaris and x86/Solaris platforms on www.sunfreeware.com.
• Jess Portnoy: Reworking the rpm package and integrating argtable into Fedora Linux.
• Michael Brown: Incorporating support for pkg-config into the autoconf scripts.
• Alexander Lindert: For extensions to the parser to support hex, octal and binary integer formats as well as KB/MB/GB suffixes.
• Rob Zaborowski: Providing build configuration files for CMake.
• Moczik Gabor: For bug fixes relating to the parsing of filepaths and filename extensions.