autosetup

https://msteveb.github.io/autosetup/
Admin
autosetup is a lightweight, fast, and flexible tool similar to autoconf, designed to configure build...
Tokens:21,794
Snippets:255
Trust Score:9.7
Update:2 months ago
Show doc for...
Tokens:
Raw
### Perform a system-wide installation

Source: https://msteveb.github.io/autosetup/developer/sysinstall

Install autosetup to a directory in the system PATH.

```bash
$ ./autosetup --sysinstall=/usr/local
Installed system autosetup v0.6.7 to /usr/local/bin/autosetup
```

--------------------------------

### Verify installed autosetup files

Source: https://msteveb.github.io/autosetup/developer/sysinstall

List the files installed in the bin directory to confirm the installation.

```bash
$ /bin/ls -1 /usr/local/bin/autosetup*
/usr/local/bin/autosetup
/usr/local/bin/autosetup-config.guess
/usr/local/bin/autosetup-config.sub
/usr/local/bin/autosetup-find-tclsh
/usr/local/bin/autosetup-test-tclsh
```

--------------------------------

### Supporting standard installation in Makefile.in

Source: https://msteveb.github.io/autosetup/developer/advanced

Configure Makefile.in to respect prefix and DESTDIR for installation paths.

```makefile
prefix = @prefix@
...
install: all
    @echo Installing from @srcdir@ and @builddir@ to $(DESTDIR)$(prefix)
```

--------------------------------

### Clone and enter the autosetup repository

Source: https://msteveb.github.io/autosetup/developer/sysinstall

Initial step to obtain the source code required for a system-wide installation.

```bash
$ git clone git://github.com/msteveb/autosetup.git
...
$ cd autosetup
```

--------------------------------

### Example Configuration Defines

Source: https://msteveb.github.io/autosetup/developer

Sample name/value pairs representing the build environment state.

```text
srcdir=.
target=x86_64-apple-darwin10.7.0
HAVE_STDLIB_H=1
CC=arm-linux-gcc
SIZEOF_LONG_LONG=8
```

--------------------------------

### Install autosetup into a project

Source: https://msteveb.github.io/autosetup/download

Initialize autosetup in an existing project directory to enable the build system.

```bash
$ cd ~/src/myproject
$ ~/src/autosetup/autosetup --install --init=make
Installed local autosetup v0.6.7 to autosetup
Initialising make: Simple "make" build system

I see auto.def already exists.
Note: I don't see Makefile.in. You will probably need to create one.
```

--------------------------------

### Configure and install with DESTDIR

Source: https://msteveb.github.io/autosetup/user/installing

Use this sequence to configure a project for a specific prefix and perform a staged installation into a temporary directory.

```bash
$ ./configure --prefix=/usr
$ make DESTDIR=/tmp/staging install
```

--------------------------------

### Configure command line flag examples

Source: https://msteveb.github.io/autosetup/articles/handling-cflags

Examples of how users provide flags to the configure script via environment variables or command line arguments.

```bash
$ CFLAGS=-Dd1 ./configure CFLAGS=-Dd2
```

```bash
$ CFLAGS=-Dd3 make CFLAGS=-Dd4
```

--------------------------------

### Typical autosetup installation file list

Source: https://msteveb.github.io/autosetup/developer

The standard file structure created after running the autosetup initialization command.

```text
auto.def
configure
autosetup/LICENSE
autosetup/README.autosetup
autosetup/autosetup
autosetup/autosetup-config.guess
autosetup/autosetup-config.sub
autosetup/autosetup-find-tclsh
autosetup/autosetup-test-tclsh
autosetup/cc-db.tcl
autosetup/cc-lib.tcl
autosetup/cc-shared.tcl
autosetup/cc.tcl
autosetup/default.auto
autosetup/jimsh0.c
autosetup/pkg-config.tcl
autosetup/system.tcl
autosetup/tmake.auto
autosetup/tmake.tcl
```

--------------------------------

### Defining installation directories

Source: https://msteveb.github.io/autosetup/developer/advanced

Create a define variable to capture specific installation paths like library locations.

```tcl
define TCL_LIBRARY [get-define prefix]/lib/jim
```

--------------------------------

### View String Options in Help

Source: https://msteveb.github.io/autosetup/user

Example output from configure --help showing string option definitions with default values.

```text
--manual?=text?      display the autosetup manual. Other formats: 'wiki', 'asciidoc',
                     'markdown'
--host=host-alias    a complete or partial cpu-vendor-opsys for the system where the
                     application will run (defaults to the same value as --build)
```

--------------------------------

### View Boolean Options in Help

Source: https://msteveb.github.io/autosetup/user

Example output from configure --help showing boolean option definitions.

```text
--shared             Create a shared library
--disable-utf8       Disable utf8 support
```

--------------------------------

### Autoconf-compatible installation override options

Source: https://msteveb.github.io/autosetup/user/installing

These options allow overriding specific installation directories, though their use is generally discouraged.

```text
--includedir
--mandir
--infodir
--libexecdir
--sysconfdir
--localstatedir
```

--------------------------------

### Compiler flag check

Source: https://msteveb.github.io/autosetup/articles/handling-cflags

Example of checking for compiler flag support using autosetup.

```tcl
# If supported, add this flag to compiler flags
cc-check-flags -std=c99
```

--------------------------------

### Redis auto.def configuration

Source: https://msteveb.github.io/autosetup/developer/examples

A complex configuration example demonstrating platform-specific logic, library dependency checks, and multiple template generation.

```tcl
use cc

# Add any user options here
options {
    tcmalloc => "Use the tcmalloc allocator"
}

# Headers we may need
cc-check-includes AvailabilityMacros.h

# Libraries we may need
if {![cc-check-function-in-lib pthread_create pthread]} {
    user-error "Sorry, pthreads are needed for redis-server"
}
cc-check-function-in-lib sin m
cc-check-function-in-lib gethostbyaddr nsl
cc-check-function-in-lib socket socket
cc-check-function-in-lib dlopen dl

define EXTRA_CFLAGS ""

switch -glob -- [lindex [split [get-define host] -] end] {
    darwin* { define host_os darwin }
    sunos* { define host_os sunos }
    qnx* {
        define host_os qnx
        define-append EXTRA_CFLAGS -D_QNX_SOURCE -Du_int32_t=int
    }
    default { define host_os other }
}

cc-check-tools ar ranlib

define HAVE_TCMALLOC 0
if {[opt-bool tcmalloc]} {
    if {[cc-check-function-in-lib tc_malloc tcmalloc]} {
        define-append EXTRA_CFLAGS -DUSE_TCMALLOC
        cc-check-function-in-lib tc_malloc_size tcmalloc
    } else {
        user-error "I can't find tcmalloc"
    }
} else {
    cc-check-includes malloc/malloc.h
    cc-check-functions malloc_size
}

# We always set _FILE_OFFSET_BITS=64
# If that doesn't make off_t 64 bits, it is an error

cc-check-includes sys/types.h
msg-checking "Checking for LFS..."
if {[msg-quiet cc-with {-includes sys/types.h -cflags -D_FILE_OFFSET_BITS=64} \
	{cc-check-sizeof off_t}] == 8} {

    define _FILE_OFFSET_BITS 64
    msg-result yes
} else {
    user-error "LFS not available"
}

# Functions we may need
cc-check-functions fdatasync kqueue epoll backtrace task_info

make-autoconf-h src/autoconf.h {HAVE_* USE*}
make-template Makefile.in
make-template src/Makefile.in
make-template deps/linenoise/Makefile.in
make-template deps/hiredis/Makefile.in
```

--------------------------------

### Retrieve pkg-config variable

Source: https://msteveb.github.io/autosetup/developer/reference

Example of checking for a module and retrieving a specific variable value.

```tcl
if {[pkg-config harfbuzz >= 2.5]} {
  define harfbuzz_libdir [pkg-config-get-var harfbuzz libdir]
}
```

--------------------------------

### tmake Configuration File Output

Source: https://msteveb.github.io/autosetup/developer/reference

Example of the output format generated by make-tmake-settings for a defined variable.

```text
define ABC {3 monkeys}
```

--------------------------------

### Generated Header File Example

Source: https://msteveb.github.io/autosetup/developer

A typical C/C++ header file generated by make-config-header based on configuration variables.

```c
#ifndef _AUTOCONF_H
#define _AUTOCONF_H
#define HAVE_BACKTRACE 1
#define HAVE_DLFCN_H 1
#define HAVE_DLOPEN 1
#define HAVE_FORK 1
#define HAVE_GETADDRINFO 1
#define HAVE_GETEUID 1
#define HAVE_INET_NTOP 1
#define HAVE_LONG_LONG 1
/* #undef HAVE_SYSINFO */
#define HAVE_SYSLOG 1
#define TCL_PLATFORM_OS "Darwin"
#define TCL_PLATFORM_PLATFORM "unix"
#define SIZEOF_LONG_LONG 8
#endif
```

--------------------------------

### Override Environment Variables

Source: https://msteveb.github.io/autosetup/user

Example of setting environment variables on the command line during configuration.

```bash
$ ./configure --utf8 CFLAGS="-Os"
```

--------------------------------

### User-specified CFLAGS via make

Source: https://msteveb.github.io/autosetup/news

Example of providing CFLAGS through environment variables and command-line arguments to make.

```bash
$ CFLAGS=-Dd3 make CFLAGS=-Dd4
```

--------------------------------

### Module use declaration

Source: https://msteveb.github.io/autosetup/developer

Example of importing core modules for C/C++ compilation and shared library support.

```tcl
# The C/C++ compiler will be used and shared libraries may be needed
use cc cc-shared
```

--------------------------------

### User-specified CFLAGS via command line

Source: https://msteveb.github.io/autosetup/news

Example of providing CFLAGS through environment variables and command-line arguments to configure.

```bash
$ CFLAGS=-Dd1 ./configure CFLAGS=-Dd2
```

--------------------------------

### Check for a Feature

Source: https://msteveb.github.io/autosetup/developer/reference

Example of using check-feature to define a constant based on a C test.

```tcl
check-feature const {
    cctest -code {const int _x = 0;}
}
```

--------------------------------

### Run configure in MSYS bash shell

Source: https://msteveb.github.io/autosetup/articles/msys-mingw-support

Example output of executing the configure script within an MSYS/MinGW environment.

```bash
$ cd examples/typical
$ ./configure
No installed jimsh or tclsh, building local bootstrap jimsh0
Host System...i686-pc-mingw32
Build System...i686-pc-mingw32
C compiler... gcc -g -O2
C++ compiler... c++ -g -O2
Checking for stdlib.h...ok
Checking for long long...ok
Checking for sizeof long long...8
Checking for sizeof void *...4
Checking for sys/un.h...not found
Checking for regcomp...not found
Checking for waitpid...not found
Checking for sigaction...not found
Checking for sys_signame...not found
Checking for sys_siglist...not found
Checking for syslog...not found
Checking for opendir...ok
Checking for readlink...not found
Checking for sleep...not found
Checking for usleep...ok
Checking for pipe...not found
Checking for inet_ntop...not found
Checking for getaddrinfo...not found
Enabling UTF-8
Building static library
Created config.h
Created Makefile from Makefile.in
```

--------------------------------

### Find package module with pkg-config

Source: https://msteveb.github.io/autosetup/developer/reference

Example usage of the pkg-config command to locate a specific module version.

```tcl
pkg-config pango >= 1.37.0
```

--------------------------------

### Initial Makefile CFLAGS assignment attempt

Source: https://msteveb.github.io/autosetup/news

A potential starting point for assigning flags in a Makefile.

```makefile
CFLAGS += @AS_CFLAGS@ @AS_CPPFLAGS@ @CFLAGS@ @CPPFLAGS@
```

--------------------------------

### Initialize a project with autosetup

Source: https://msteveb.github.io/autosetup/developer/sysinstall

Create a project-specific configuration using the system-installed autosetup.

```bash
$ mkdir myproject
$ cd myproject
$ autosetup --install
autosetup v0.6.7 creating configure to use system-installed autosetup
I don't see configure, so I will create it.
Creating autosetup/README.autosetup
$ find . -type f
./autosetup/README.autosetup
./configure
```

--------------------------------

### Makefile conditional flag assignment

Source: https://msteveb.github.io/autosetup/articles/handling-cflags

Example of conditionally appending flags in a Makefile.

```makefile
ifeq(@SHARED@,1)
# Except we don't want to append to CFLAGS
CFLAGS += -dynamic
endif
```

--------------------------------

### Typical configuration and build process

Source: https://msteveb.github.io/autosetup/user

Standard workflow for configuring and building a project using make.

```bash
$ ./configure
...output...
$ make
...output...
```

--------------------------------

### Build the project

Source: https://msteveb.github.io/autosetup/download

Execute the make command to compile the source code after configuration.

```bash
$ make
cc -g -O2 -D_GNU_SOURCE -Wall -Werror -I.  -c -o main.o main.c
cc -g -O2 -D_GNU_SOURCE -Wall -Werror -I.  -c -o funcs.o funcs.c
ar cr libtest.a funcs.o
ranlib libtest.a
cc -g -O2   -o app main.o libtest.a
```

--------------------------------

### Clone the autosetup repository

Source: https://msteveb.github.io/autosetup/download

Use git to download the latest version of autosetup from the official repository.

```bash
$ git clone git://github.com/msteveb/autosetup.git
Initialized empty Git repository in /Users/steveb/autosetup/.git/
remote: Counting objects: 311, done.
remote: Compressing objects: 100% (299/299), done.
remote: Total 311 (delta 179), reused 0 (delta 0)
Receiving objects: 100% (311/311), 311.07 KiB | 26 KiB/s, done.
Resolving deltas: 100% (179/179), done.
```

--------------------------------

### Configure a project

Source: https://msteveb.github.io/autosetup/developer/sysinstall

Run the generated configure script to initialize the build system.

```bash
$ ./configure --init=make
Initialising make: Simple "make" build system

I don't see auto.def, so I will create it.
Note: I don't see Makefile.in. You will probably need to create one.
```

--------------------------------

### Run configure with options

Source: https://msteveb.github.io/autosetup/user

Execute the configure script with specific host, feature, and compiler flag options.

```bash
$ ./configure --host=arm-linux --utf8 --with-ext="regexp tree" --prefix=/usr CFLAGS="-g -Os"
```

--------------------------------

### Run basic configure script

Source: https://msteveb.github.io/autosetup/user

Execute the configure script to adapt the project to the local environment.

```bash
$ ./configure
```

--------------------------------

### Migrating a project using migrate-autoconf

Source: https://msteveb.github.io/autosetup/articles/autoconf-migration

Commands to run the migration tool and initialize autosetup in a project directory.

```bash
$ cd tinytcl
$ ~/src/autosetup.git/migrate-autoconf
Migrating configure.ac to auto.def
Created auto.def. Now edit to resolve items marked XXX
$ ~/src/autosetup.git/autosetup --install
Installed autosetup v0.6.2 to autosetup/
I see configure, but not created by autosetup, so I won't overwrite it.
Use autosetup --init --force to overwrite.
$ ./autosetup/autosetup --init --force
I will overwrite the existing configure because you used --force.
```

--------------------------------

### Display configure help

Source: https://msteveb.github.io/autosetup/user

View the available command-line options and settings for the configure script.

```text
Usage: configure [options] [settings]

   This is autosetup, a faster, better alternative to autoconf.
   Use the --manual option for the full autosetup manual.

  --help?=local?       display help and options. Optionally specify a module name, such
                       as --help=system
  --version            display the version of autosetup
  --manual?=text?      display the autosetup manual. Other formats: 'wiki', 'asciidoc',
                       'markdown'
  --debug              display debugging output as autosetup runs
  --install            install autosetup to the current directory (in the 'autosetup/'
                       subdirectory)
  --init               create an initial 'configure' script if none exists
  --host=host-alias    a complete or partial cpu-vendor-opsys for the system where the
                       application will run (defaults to the same value as --build)
  --build=build-alias  a complete or partial cpu-vendor-opsys for the system where the
                       application will be built (defaults to the result of running
                       config.guess)
  --prefix=dir         the target directory for the build (defaults to /usr/local)
  Local Options:
  --shared             Create a shared library
  --disable-utf8       Disable utf8 support
  --disable-largefile  Disable large file support
```

--------------------------------

### Simple auto.def configuration

Source: https://msteveb.github.io/autosetup/developer/examples

A basic configuration file demonstrating package definition, feature toggles, and system checks.

```tcl
use cc cc-shared

options {
    shared -> "Build a shared library rather than a static library"
    utf8=1 -> "Disable UTF-8 support"
}

define PACKAGE_NAME "testpackage"
define PACKAGE_VERSION 1.0

if {[cc-check-types "long long"]} {
    cc-check-sizeof "long long"
}
cc-check-sizeof "void *"

cc-check-includes sys/un.h

cc-check-functions regcomp waitpid sigaction sys_signame sys_siglist
cc-check-functions syslog opendir readlink sleep usleep pipe inet_ntop getaddrinfo

# Find some tools
cc-check-tools ar ranlib strip

set extra_objs {}

if {[opt-bool utf8]} {
    msg-result "Enabling UTF-8"
    define ENABLE_UTF8
}
if {[opt-bool shared]} {
    msg-result "Building shared library"
    define shared 1
} else {
    msg-result "Building static library"
    define shared ""
}

make-autoconf-h config.h {HAVE_* SIZEOF_* ENABLE_* PACKAGE_*}
make-template Makefile.in
```

--------------------------------

### Custom Autosetup Module Structure

Source: https://msteveb.github.io/autosetup/developer/advanced

A template for creating custom Tcl modules, including documentation synopsis, options, and command definitions.

```tcl
# @synopsis:
#
# Documentation for this module. Environment variables should be documented here.

module-options {
    modopt => "A boolean option"
}

# @check-erlang-feature name expression
#
# Runs the erlang code 'expression' and defines the
# given feature if the code succeeds (returns 0).
#
# See 'feature-define-name' for how the feature name
# is translated into the define name.
#
proc check-erlang-feature {name expression} {
    define [feature-define-name $name] [erlang-run $expression]
}

msg-result "Erlang module loaded"

```

--------------------------------

### Typical auto.def configuration file

Source: https://msteveb.github.io/autosetup/developer

A standard configuration file demonstrating module usage, option declarations, feature checks, and conditional logic.

```tcl
use cc

options {
    shared => "build a shared library"
    lineedit=1 => "disable line editing"
    utf8 => "enabled UTF-8 support"
    with-regexp regexp => "use regexp"
}

cc-check-types "long long"
cc-check-includes sys/un.h dlfcn.h
cc-check-functions ualarm sysinfo lstat fork vfork
cc-check-function-in-lib sqlite3_open sqlite3

if {[opt-bool utf8] && [have-feature fork]} {
    msg-result "Enabling UTF-8"
    define JIM_UTF8
}
make-config-header config.h
make-template Makefile.in
```

--------------------------------

### Typical Makefile.in Template

Source: https://msteveb.github.io/autosetup/developer/advanced

A Makefile template designed for autosetup that handles tool definitions, VPATH support, and automatic reconfiguration.

```makefile
# Example of a typical Makefile template for autosetup

# Tools. CC is standard. The rest are via cc-check-tools
CC = @CC@
RANLIB = @RANLIB@
AR = @AR@
STRIP = @STRIP@

# FLAGS/LIBS
CFLAGS = @CFLAGS@
LDFLAGS = @LDFLAGS@
LDLIBS += @LIBS@

# Install destination
prefix = @prefix@
exec_prefix = @exec_prefix@
DESTDIR = $(prefix)

# Project-specific CFLAGS
CPPFLAGS += -D_GNU_SOURCE -Wall -Werror -I.

# VPATH support for out-of-tree build
ifneq (@srcdir@,.)
CPPFLAGS += -I@srcdir@
VPATH := @srcdir@
endif

APPOBJS := main.o
LIBOBJS := funcs.o

APP := app@EXEEXT@

all: $(APP)

# shared vs. static library
ifeq (@shared@,1)
# Shared library support from cc-shared
LIB = libtest.so
# All objects destined for the shared library need these flags
CPPFLAGS += @SH_CFLAGS@

$(LIB): $(LIBOBJS)
    $(CC) $(CFLAGS) $(LDFLAGS) @SH_LDFLAGS@ -o $@ $^ $(LDLIBS)

else
LIB = libtest.a

$(LIB): $(LIBOBJS)
    $(AR) cr $@ $^
    $(RANLIB) $@
endif

$(APP): $(APPOBJS) $(LIB)
    $(CC) $(CFLAGS) $(LDFLAGS) @SH_LINKFLAGS@ -o $@ $(APPOBJS) $(LIB) $(LDLIBS)

install: all
    @echo Installing from @srcdir@ and `pwd` to $(DESTDIR)

clean:
    rm -f *.o *.so lib*.a $(APP) conftest.*

distclean: clean
    rm -f config.h Makefile config.log

# automake compatibility. do nothing for all these targets
EMPTY_AUTOMAKE_TARGETS := dvi pdf ps info html tags ctags mostlyclean maintainer-clean check installcheck installdirs \
 install-pdf install-ps install-info install-html -install-dvi uninstall install-exec install-data distdir
.PHONY: $(EMPTY_AUTOMAKE_TARGETS)
$(EMPTY_AUTOMAKE_TARGETS):

# Reconfigure if needed
ifeq ($(findstring clean,$(MAKECMDGOALS)),)
Makefile: @AUTODEPS@ @srcdir@/Makefile.in
    @@AUTOREMAKE@
endif

# Or on demand
reconfig:
    @AUTOREMAKE@
```

--------------------------------

### Configure the project

Source: https://msteveb.github.io/autosetup/download

Run the configure script within a project directory to detect system settings and generate build files.

```bash
$ cd autosetup/examples/typical
$ ./configure
Host System...x86_64-apple-darwin10.7.0
Build System...x86_64-apple-darwin10.7.0
C compiler...ccache cc -g -O2
C++ compiler...ccache c++ -g -O2
Checking for stdlib.h...ok
Checking for long long...ok
Checking for sizeof long long...8
Checking for sizeof void *...8
Checking for sys/un.h...ok
Checking for regcomp...ok
...etc...
Enabling UTF-8
Building static library
Created config.h
Created Makefile from Makefile.in
```

--------------------------------

### autosetup-require-version required

Source: https://msteveb.github.io/autosetup/developer/reference

Validates the current autosetup version.

```APIDOC
## autosetup-require-version required

### Description
Checks the current version of autosetup against the required version. A fatal error is generated if the current version is less than that required.
```

--------------------------------

### Enforce autosetup version requirements

Source: https://msteveb.github.io/autosetup/developer/sysinstall

Add a version check to the auto.def file to ensure compatibility.

```tcl
# This will given an error if the current autosetup version is < 0.6.7
autosetup-require-version 0.6.7

use cc

# Add any user options here
options {
}
...
```

--------------------------------

### Debugging with the cc module

Source: https://msteveb.github.io/autosetup/developer/advanced

Use the autosetup debug flag to log compilation details to config.log.

```tcl
if {$::autosetup(debug)} {
    configlog "Compiled OK: [join $cmdline]"
}
```

--------------------------------

### pkg-config-init

Source: https://msteveb.github.io/autosetup/developer/reference

Initializes the pkg-config system. If required is set to 1 (default), it is a fatal error if pkg-config is not found.

```APIDOC
## pkg-config-init ?required?

### Description
Initializes the pkg-config system. Unless $required is set to 0, it is a fatal error if a usable pkg-config is not found.

### Parameters
- **required** (boolean) - Optional - If set to 0, returns 0 instead of throwing a fatal error if pkg-config is not found.

### Returns
- **1** (integer) - If pkg-config is found and usable.
- **0** (integer) - If pkg-config is not found/usable (only if required is 0).
```

--------------------------------

### Usage of make-tmake-settings

Source: https://msteveb.github.io/autosetup/developer/reference

Typical command usage to generate a settings.conf file based on environment variables matching a pattern.

```bash
make-tmake-settings [get-env BUILDDIR objdir]/settings.conf {[A-Z]*}
```

--------------------------------

### Build Variables

Source: https://msteveb.github.io/autosetup/developer/reference

Variables defined from environment settings.

```text
CC_FOR_BUILD
LD
```

--------------------------------

### Update configure wrapper for renamed autosetup

Source: https://msteveb.github.io/autosetup/developer/sysinstall

Modify the configure script to point to a specific version of the autosetup binary.

```bash
$ cat configure
#!/bin/sh
# Explicitly use the renamed autosetup0.6.7
WRAPPER="-"; "autosetup0.6.7" "$@"
```

--------------------------------

### Configure help output

Source: https://msteveb.github.io/autosetup/developer

The generated help output displayed when running ./configure --help.

```text
$ ./configure --help
...standard help...
  Local Options:
  --boolopt             a boolean option which defaults to disabled
  --disable-boolopt2    a boolean option which defaults to enabled
  --stringopt=          an option which takes an argument, e.g. --stringopt=value
  --stringopt2?=value?  an option where the argument is optional and defaults to 'value'
  --booltopt3           a boolean with a hidden alias. --optalias is not shown in --help
  --boolopt4
        Multi-line description for this option
        which is carefully formatted.
```

--------------------------------

### Create a release build out-of-tree

Source: https://msteveb.github.io/autosetup/user/outoftree

Commands to configure and build a release version of the project in a separate directory.

```bash
$ mkdir build-release
$ cd build-release
$ ../configure CFLAGS="-O2"
$ make
$ cd ..
```

--------------------------------

### cc-with settings ?{ script }?

Source: https://msteveb.github.io/autosetup/developer/reference

Sets the given cctest settings and optionally runs the provided script. Settings like -lang replace current settings, while others like -includes are appended.

```APIDOC
## cc-with settings ?{ script }?

### Description
Sets the given cctest settings and then runs the tests in the provided script. If no script is given, the settings become the default for the remainder of the auto.def file.

### Parameters
- **settings** (list) - Required - A list of configuration settings (e.g., -lang, -includes, -libs).
- **script** (code block) - Optional - The script to execute with the specified settings.
```

--------------------------------

### Direct Definition Commands

Source: https://msteveb.github.io/autosetup/developer

Use define and define-feature to manually set configuration variables based on user options.

```tcl
define VERSION 1.1.3
if {[opt-bool utf8]} {
    define USE_UTF8
}
define-feature regcomp
```

--------------------------------

### Platform-Specific Configuration

Source: https://msteveb.github.io/autosetup/developer/examples

Handles Windows-specific library linking and regex engine selection.

```tcl
if {[have-feature windows]} {
    if {"aio" in "$ext $extmod"} {
        define-append LIBS -lwsock32
    }
    lappend extra_objs jim-win32compat.o

    if {$extmod ne "" && [get-define JIM_LIBTYPE] eq "static"} {
        user-error "cygwin/mingw require --shared for dynamic modules"
    }
}

if {"regexp" in "$ext $extmod"} {
    # No regcomp means we need to use the built-in version
    if {![have-feature regcomp]} {
        incr jimregexp
    }
}

if {$jimregexp || [opt-bool jim-regexp]} {
    msg-result "Using built-in regexp"
    define JIM_REGEXP
```

--------------------------------

### make-tmake-settings

Source: https://msteveb.github.io/autosetup/developer/reference

Examines defined variables matching specified patterns and writes them to a tmake-compatible configuration file.

```APIDOC
## make-tmake-settings outfile patterns ...

### Description
Examines all defined variables which match the given patterns and writes a tmake-compatible .conf file defining those variables. If the resulting file content would be unchanged, the file is not written.

### Usage
`make-tmake-settings [outfile] [patterns ...]`

### Parameters
- **outfile** (string) - Required - The path to the output .conf file.
- **patterns** (string) - Optional - Patterns to match against defined variables (defaults to '*').

### Example
`make-tmake-settings [get-env BUILDDIR objdir]/settings.conf {[A-Z]*}`
```

--------------------------------

### Configure compiler settings with cc-with

Source: https://msteveb.github.io/autosetup/developer/reference

Use cc-with to scope compiler settings like language and includes. Settings like -lang replace current values, while -includes are appended.

```tcl
cc-with {-lang c++} {
  # This will check with the C++ compiler
  cc-check-types bool
  cc-with {-includes signal.h} {
    # This will check with the C++ compiler, signal.h and any existing includes.
    ...
  }
  # back to just the C++ compiler
}
```

```tcl
cc-with {-libs {-lc -lm}} {
  cc-with {-libs -ldl} {
    cctest -libs -lsocket ...
    # libs will be in this order: -lsocket -ldl -lc -lm
  }
}
```

```tcl
cc-with {} {
  cc-check-flags ...
}
```

--------------------------------

### Initial auto.def file content

Source: https://msteveb.github.io/autosetup/articles/autoconf-migration

The generated auto.def file before manual editing, containing placeholders marked with XXX.

```tcl
# Created by migrate-autoconf - fix items marked XXX

use cc cc-lib

options {
    shared=0         =>  {Build a shared library}
    history=0        =>  {Enable history support}
    debug=0          =>  {Enable debugging command: cmdtrace}
    fork=1           =>  {Do not use fork (no exec, etc.)}
    syslog=0         =>  {Build the syslog extension}
}

#                                               -*- Autoconf -*-
# Process this file with autoconf to produce a configure script.


# XXX autosetup automatically substitutes all define'd values
#     In general, simply 'define' the value rather than using a shell
#     variable and AC_SUBST.
#
# XXX AC_SUBST TARGET_PLATFORM $ac_cv_host

# Checks for programs.

# XXX TINYTCL_IS_STATIC=1
if {[opt-bool shared]} {
    # XXX if test "x$enableval" = "xyes" ; then
    msg-result "* creating shared library"
    # XXX TINYTCL_IS_STATIC=
    # XXX fi
}
# XXX AC_SUBST TINYTCL_IS_STATIC $TINYTCL_IS_STATIC
...
```

--------------------------------

### Default configuration header patterns

Source: https://msteveb.github.io/autosetup/developer/reference

The default pattern matching behavior for the make-config-header command.

```text
 -bare {SIZEOF_* HAVE_DECL_*} -auto HAVE_* -none *
```

--------------------------------

### Check for programs

Source: https://msteveb.github.io/autosetup/developer/autoconf

Use cc-check-progs to verify the existence of required system utilities.

```tcl
if {![cc-check-progs grep]} {
    user-error "You don't have grep, but we need it"
}
foreach prog {gawk mawk nawk awk false} {
    if {[cc-check-progs $prog]} {
        define AWK $prog
        break
    }
}
# If not found, AWK is defined as false
```

--------------------------------

### Create a debug build out-of-tree

Source: https://msteveb.github.io/autosetup/user/outoftree

Commands to configure and build a debug version of the project in a separate directory.

```bash
$ mkdir build-debug
$ cd build-debug
$ ../configure CFLAGS="-g -O0"
$ make
$ cd ..
```

--------------------------------

### make-config-header outfile ?-auto patternlist? ?-bare patternlist? ?-none patternlist? ?-str patternlist?

Source: https://msteveb.github.io/autosetup/developer/reference

Examines defined variables matching given patterns and writes an include file defining them.

```APIDOC
## make-config-header outfile ?-auto patternlist? ?-bare patternlist? ?-none patternlist? ?-str patternlist?

### Description
Examines all defined variables which match the given patterns and writes an include file, $file, which defines each of these. The first pattern that matches is selected.

### Parameters
- **outfile** (string) - Required - The path to the output header file.
- **-auto** (list) - Optional - Patterns for variables to be auto-formatted.
- **-bare** (list) - Optional - Patterns for variables to be defined as-is.
- **-none** (list) - Optional - Patterns for variables to be omitted.
- **-str** (list) - Optional - Patterns for variables to be defined as strings.
```

--------------------------------

### Final Makefile command line implementation

Source: https://msteveb.github.io/autosetup/articles/handling-cflags

The recommended command line structure in a Makefile using AS_CFLAGS and AS_CPPFLAGS.

```makefile
cc $(AS_CFLAGS) $(AS_CPPFLAGS) $CFLAGS $CPPFLAGS -c ... -o ...
```

```makefile
CFLAGS += @AS_CFLAGS@ @AS_CPPFLAGS@ @CFLAGS@ @CPPFLAGS@
```

```makefile
override CFLAGS := @AS_CFLAGS@ @AS_CPPFLAGS@ $(CFLAGS)
```

--------------------------------

### Compare Versions

Source: https://msteveb.github.io/autosetup/developer/reference

Returns -1, 0, or 1 based on the comparison of two version strings.

```text
-1 if v1 < v2
 0 if v1 == v2
 1 if v1 > v2
```

```text
0.2   <  0.3
0.2.5 >  0.2
1.1   == 1.1.0
```

--------------------------------

### Configure for cross-compilation

Source: https://msteveb.github.io/autosetup/user/crosscompiling

Use the --host flag to specify the target toolchain prefix for standard GNU-named tools.

```bash
$ ./configure --host=arm-linux
```

--------------------------------

### Define argument options

Source: https://msteveb.github.io/autosetup/developer/reference

Specifies configuration options that accept parameters, including optional values and defaults.

```tcl
name:value         => "Description of this option"
name:value=default => "Description of this option with a default value"
name:=value        => "Description of this option with an optional value"
```

--------------------------------

### options-defaults dictionary

Source: https://msteveb.github.io/autosetup/developer/reference

Sets default values for options before modules are loaded.

```APIDOC
## options-defaults dictionary

### Description
Specifies a dictionary of options and a new default value for each of those options. Should be used before any use statements in auto.def.
```

--------------------------------

### Jim Tcl auto.def Configuration

Source: https://msteveb.github.io/autosetup/developer/examples

This configuration file handles project options, checks for system types and functions, and defines build features. It must be processed by the Jim Tcl build system.

```tcl
# Note: modules which support options *must* be included before 'options'
use cc cc-shared

options {
    utf8            => "include support for utf8-encoded strings"
    lineedit=1      => "disable line editing"
    references=1    => "disable support for references"
    math            => "include support for math functions"
    ipv6            => "include ipv6 support in the aio extension"
    maintainer      => {enable the [debug] command and JimPanic}
    with-jim-shared shared => "build a shared library instead of a static library"
    jim-regexp      => "use the built-in regexp, even if POSIX regex is available"
    with-jim-ext: {with-ext:"ext1 ext2 ..."} => {
        Specify additional jim extensions to include.
        These are enabled by default:

        aio       - ANSI I/O, including open and socket
        eventloop - after, vwait, update
        array     - Tcl-compatible array command
        clock     - Tcl-compatible clock command
        exec      - Tcl-compatible exec command
        file      - Tcl-compatible file command
        glob      - Tcl-compatible glob command
        readdir   - Required for glob
        package   - Package management with the package command
        load      - Load binary extensions at runtime with load or package
        posix     - Posix APIs including os.fork, os.wait, pid
        regexp    - Tcl-compatible regexp, regsub commands
        signal    - Signal handling
        stdlib    - Built-in commands including lassign, lambda, alias
        syslog    - System logging with syslog
        tclcompat - Tcl compatible read, gets, puts, parray, case, ...

        These are disabled by default:

        nvp       - Name-value pairs C-only API
        oo        - Jim OO extension
        tree      - OO tree structure, similar to tcllib ::struct::tree
        binary    - Tcl-compatible 'binary' command
        readline  - Interface to libreadline
        rlprompt  - Tcl wrapper around the readline extension
        sqlite    - Interface to sqlite
        sqlite3   - Interface to sqlite3
        win32     - Interface to win32
    }
    with-out-jim-ext: {without-ext:"default|ext1 ext2 ..."} => {
        Specify jim extensions to exclude.
        If 'default' is given, the default extensions will not be added.
    }
    with-jim-extmod: {with-mod:"ext1 ext2 ..."} => {
        Specify jim extensions to build as separate modules (either C or Tcl).
        Note that not all extensions can be built as loadable modules.
    }
}

cc-check-types "long long"

cc-check-includes sys/un.h dlfcn.h unistd.h crt_externs.h

cc-check-functions ualarm sysinfo lstat fork vfork
cc-check-functions backtrace geteuid mkstemp realpath strptime
cc-check-functions regcomp waitpid sigaction sys_signame sys_siglist
cc-check-functions syslog opendir readlink sleep usleep pipe inet_ntop getaddrinfo

switch -glob -- [get-define host] {
    *-*-ming* {
        # We provide our own implementation of dlopen for mingw32
        define-feature dlopen-compat
    }
}

# Find some tools
cc-check-tools ar ranlib strip
define tclsh [info nameofexecutable]

if {![cc-check-functions _NSGetEnviron]} {
    msg-checking "Checking environ declared in unistd.h..."
    if {[cctest -cflags -D_GNU_SOURCE -includes unistd.h -code {char **ep = environ;}]} {
        define NO_ENVIRON_EXTERN
        msg-result "yes"
    } else {
        msg-result "no"
    }
}

set extra_objs {}
set jimregexp 0

if {[opt-bool utf8]} {
    msg-result "Enabling UTF-8"
    define JIM_UTF8
    incr jimregexp
}
if {[opt-bool maintainer]} {
    msg-result "Enabling maintainer settings"
    define JIM_MAINTAINER
}
if {[opt-bool math]} {
    msg-result "Enabling math functions"
    define JIM_MATH_FUNCTIONS
    define-append LIBS -lm
}
if {[opt-bool ipv6]} {
    msg-result "Enabling IPv6"
    define JIM_IPV6
}
if {[opt-bool lineedit] && [cc-check-includes termios.h]} {
    msg-result "Enabling line editing"
    define USE_LINENOISE
    lappend extra_objs linenoise.o
}
if {[opt-bool references]} {
    msg-result "Enabling references"
    define JIM_REFERENCES
}
if {[opt-bool shared with-jim-shared]} {
    msg-result "Building shared library"
    define JIM_LIBTYPE shared
} else {
    msg-result "Building static library"
    define JIM_LIBTYPE static
}

# Note: Extension handling is mapped directly from the configure.ac
# implementation

set without [join [opt-val {without-ext with-out-jim-ext}]]
set withext [join [opt-val {with-ext with-jim-ext}]]
set withmod [join [opt-val {with-mod with-jim-extmod}]]
```

--------------------------------

### Compiler command line structure

Source: https://msteveb.github.io/autosetup/articles/handling-cflags

Recommended structure for the compiler command line to ensure user flags take precedence.

```bash
cc <other-flags> $CFLAGS -c ... -o ...
```

--------------------------------

### Define option aliases

Source: https://msteveb.github.io/autosetup/developer/reference

Maps multiple option names to the same underlying configuration setting.

```tcl
lfs=1 largefile=1 => "Disable large file support"
```

--------------------------------

### Define Directory Variables

Source: https://msteveb.github.io/autosetup/developer/reference

List of standard directory variables defined by the system module.

```text
datadir
sysconfdir
sharedstatedir
localstatedir
infodir
mandir
includedir
```

--------------------------------

### Autosetup AS_CFLAGS configuration

Source: https://msteveb.github.io/autosetup/articles/handling-cflags

Recommended way to add flags to AS_CFLAGS in auto.def to avoid modifying user-defined CFLAGS.

```tcl
# Adds to AS_CFLAGS
cc-check-flags -std=c99
# Add profiling if selected
if {[opt-bool profiling]} {
	define-append AS_CFLAGS -pg
}
```

--------------------------------

### Options declaration syntax

Source: https://msteveb.github.io/autosetup/developer

Defines various option types including booleans, strings, and multi-line descriptions for the configure script.

```tcl
options {
    boolopt            => "a boolean option which defaults to disabled"
    boolopt2=1         => "a boolean option which defaults to enabled"
    stringopt:         => "an option which takes an argument, e.g. --stringopt=value"
    stringopt2:=value  => "an option where the argument is optional and defaults to 'value'"
    optalias booltopt3 => "a boolean with a hidden alias. --optalias is not shown in --help"
    boolopt4 => {
        Multi-line description for this option
        which is carefully formatted.
    }
}
```

--------------------------------

### Selecting C or C++ for tests

Source: https://msteveb.github.io/autosetup/developer/advanced

Use cc-with to specify the compiler language for a block of tests or the remainder of the configuration.

```tcl
cc-with {-lang c++} {
    # All tests now use the C++ compiler -- $(CXX) and $(CXXFLAGS)
    cc-check-types bool
}
# Or just set it for the rest of the file
cc-with {-lang c++}
...
```

--------------------------------

### pkg-config-get-var

Source: https://msteveb.github.io/autosetup/developer/reference

Returns the value of a specific variable from a previously detected pkg-config module.

```APIDOC
## pkg-config-get-var module variable

### Description
Return the value of the given variable from the given pkg-config module. The module must already have been successfully detected.

### Parameters
- **module** (string) - Required - The name of the module.
- **variable** (string) - Required - The variable name to retrieve.

### Returns
- **string** - The value of the variable, or an empty string if not defined.
```

--------------------------------

### tmake Configuration Variable

Source: https://msteveb.github.io/autosetup/developer/reference

The CONFIGURED variable is set to indicate that the project is configured.

```text
CONFIGURED  - to indicate that the project is configured
```

--------------------------------

### Configure Extension Dependencies

Source: https://msteveb.github.io/autosetup/developer/examples

Maps extensions to their required features or dependent extensions.

```tcl
set dep(glob) readdir
set dep(rlprompt) readline
set dep(tree) oo
set dep(binary) pack

set needs(aio) {expr {[cc-check-function-in-lib socket socket] || 1}}
set needs(exec) {have-feature vfork}
set needs(load) {expr {[have-feature dlopen-compat] || [cc-check-function-in-lib dlopen dl]}}
set needs(posix) {have-feature waitpid}
set needs(readdir) {have-feature opendir}
set needs(readline) {cc-check-function-in-lib readline readline}
set needs(signal) {expr {[have-feature sigaction] && [have-feature vfork]}}
set needs(sqlite) {cc-check-function-in-lib sqlite_open sqlite}
set needs(sqlite3) {cc-check-function-in-lib sqlite3_open sqlite3}
set needs(syslog) {have-feature syslog}
set needs(win32) {have-feature windows}
```

--------------------------------

### Override test behavior

Source: https://msteveb.github.io/autosetup/developer/autoconf

Autoconf allows overriding tests via environment variables, whereas autosetup requires explicit configuration options.

```bash
$ ac_cv_func_malloc_0_nonnull=yes ./configure
```

```bash
$ ./configure --malloc-zero-nonnull
```

--------------------------------

### Handle unchecked includes

Source: https://msteveb.github.io/autosetup/developer/autoconf

Demonstrates the warning generated when using an include file that has not been verified.

```tcl
cc-with {-includes sys/socket.h} {
    cc-check-members "struct msghdr.msg_control"
}
```

```bash
$ ./configure
Warning: using #include <sys/socket.h> which has not been checked -- ignoring
```

--------------------------------

### pkg-config-get

Source: https://msteveb.github.io/autosetup/developer/reference

Provides convenience access to the results of a previous pkg-config lookup.

```APIDOC
## pkg-config-get module setting

### Description
Convenience access to the results of pkg-config. Returns the value of the specified setting for the module.

### Parameters
- **module** (string) - Required - The name of the module.
- **setting** (string) - Required - The setting to retrieve (e.g., CFLAGS).

### Returns
- **string** - The value of the setting, or an empty string if not defined.
```

--------------------------------

### find-executable-path name

Source: https://msteveb.github.io/autosetup/developer/reference

Searches the system path for an executable. Returns the full path if found, or an empty string if not.

```APIDOC
## find-executable-path name

### Description
Searches the path for an executable with the given name. Parameters included in the name are ignored.

### Returns
- **path** (string) - The full path to the executable if found, or "" if not found.
- **status** (integer) - Returns 1 if found, or 0 if not.
```

--------------------------------

### Configure Jim Tcl Build Extensions

Source: https://msteveb.github.io/autosetup/developer/examples

Logic for validating shared library requirements and defining build-time variables for Jim Tcl extensions.

```tcl
# If the built-in regexp overrides the system regcomp, etc.
    # jim must be built shared so that the correct symbols are found
    if {[have-feature regcomp]} {
        if {"regexp" in $extmod && [get-define JIM_LIBTYPE] eq "static"} {
            user-error "Must use --shared with regexp module and built-in regexp"
        }
    }
}
if {"load" ni $ext} {
    # If we don't have load, no need to support shared objects
    define SH_LINKFLAGS ""
}

msg-result "Jim static extensions: [lsort $ext]"
if {$extmodtcl ne ""} {
    msg-result "Jim Tcl extensions: [lsort $extmodtcl]"
}
if {$extmod ne ""} {
    msg-result "Jim dynamic extensions: [lsort $extmod]"
}

define JIM_EXTENSIONS $ext
define JIM_TCL_EXTENSIONS $extmodtcl
define JIM_MOD_EXTENSIONS $extmod
foreach i $ext {
    define jim_ext_$i
}

define EXTRA_OBJS $extra_objs

define TCL_LIBRARY [get-define prefix]/lib/jim
define TCL_PLATFORM_OS [exec uname -s]
define TCL_PLATFORM_PLATFORM unix

make-autoconf-h jim-config.h {HAVE_LONG_LONG* JIM_UTF8}
make-autoconf-h jimautoconf.h {HAVE_* jim_ext_* TCL_PLATFORM_* TCL_LIBRARY USE_* JIM_*}
make-template Makefile.in
```

--------------------------------

### Pkg-config result variables

Source: https://msteveb.github.io/autosetup/developer/reference

Variables populated after a successful pkg-config module detection.

```text
PKG_PANGO_VERSION to the found version
PKG_PANGO_LIBS    to the required libs (--libs-only-l)
PKG_PANGO_LDFLAGS to the required linker flags (--libs-only-L)
PKG_PANGO_CFLAGS  to the required compiler flags (--cflags)
```
Tokens:
Raw