CONFIGURE.ACR(5)

📦
version 2.2.6 · 4 versions
, in ubuntu stonking

💖 configure.acr(5) 💖

File Formats Manual · section 5, bestie 👑

okay so this is the manual page for configure.acr(5) — the glow-up blueprint that ACR reads to spit out your final build script. it's giving main character energy for your whole build system. let's gooo ✨

🌸 NAME 🌸

configure.acr — configuration script for ACR

🎀 DESCRIPTION 🎀

configure.acr is the target file that ACR parses to generate the final configure script that your end-users actually run. no cap.

so inside this file you gotta set some directives to tell ACR what's up: which languages you're planning to use in the package, which libraries need checking, which variables get exported, the package name, the version, the vendor info, and all the other stuff. 💅

the recommended order of checks and commands is, and this is lowkey important:

  • check operating system
  • check paths
  • check required languages
  • libraries/includes/modules checks, dies
  • pkg-config checks: version/assignations
  • final conditionals and dies
  • generation of .acr files with SUBDIRS and SUBST_FILES

✨ SYNTAX ✨

the configure.acr file is a word-based configuration file for ACR. periodt.

that means every word has to be separated by a space, a tab, or newlines. and listen — the ; separator used to terminate strings also has to be its own separated word. don't sneak it onto the end of a word, she will not read it. 🫶

every one of these words is called a "keyword", and here are the types:

  • Miscelaneous-Keys — { } ;
  • Command — ( Any active keyword )
  • Conditionals — [ IF IFEQ IFEQVAL IFAND IFOR ] [IFNOT-[EQ|EQVAL|AND|OR]
  • Argument — ( keywords after commands or conditionals )
  • Comment — block comments: /* */; line comments: //. note that one-word comments have been deprecated, but you can still use line comments //
  • Definitions — global or local variable assignations, = += ?=

💜 Definitions, in detail

from version 0.4, acr supports the normal variable assignation syntax format. now you can do stuff like:

VAR = VALUE ;

and the operators mean:

  • = — resets the value of the target variable.
  • += — appends the value to the target variable.
  • ?= — checks if the target variable is yet defined, and does not overwrite its content.
  • <- — the target value gets the content of the variable defined in the text content.

🦋 Substitutions

you can use SUBDIRS to define a list of directories to find Makefile.acr files and generate Makefile peers. 👯‍♀️ and you can use it for files instead of directories too — just give it a name and it'll parse the filename.acr to generate the filename file.

you can also use ##MARK## to define a range of code to show or hide depending on the value of the MARK variable (0 or 1). (this one is available from acr 0.5) 🔥

🌈 Comments

you can add comments to your configure.acr files by using:

// comment \\

or

## comment ##

and note that you can create multi-line comments using these tags, because everything in this file is word-based. iconic.

you're also allowed to use one-word-comments, it's simple. just prefix the desired word with a hash # sign. for example: #FOO PKGNAME FOO

⭐ the ! thing

some keyword commands can be suffixed by !. this tells ACR to stop execution of the configure script when the condition fails, instead of adding one DIE for each check at the end of the script. dramatic, but effective 💀

for more information read acr(1) about the use of the -d flag.

👑 PACKAGE INFORMATION 👑

  • PKGNAME <pkgname> — sets the target package name to be used.
  • VERSION <version> — sets the version number for the target package.
  • CONTACT <name> ; <email> — sets the name of the developer and the contact mail to be used. this will export the CONTANT_NAME and CONTACT_MAIL variables.
  • DESCRIPTION <text> ; — gives a description for the package. this text is shown with ./configure -r and it's also used for the pkgconfig files.

🧚 ACR DIRECTIVES 🧚

these directives are used internally by ACR to work in a different way. iykyk.

  • USE_BACKUP — ok so this command has been deprecated for design purposes (good programmers doesn't need to use this command, their words not mine 😭) in acr 0.5, and will no longer exist in 0.6. the backup command allows you to ensure that no files will be lost by calling the ./configure script or make clean. this option interacts with SUBST_FILES and Makefile generation with -m. read doc/backup for more info.
  • EXPORT_DEFINED|ED — tells ACR to only export defined variables. this causes OUTPUT_H to export only the variables with value != "" and != "0". and OUTPUT_SH to export the != "" variables.
  • INCLUDE <module-name> — includes an external acr file from ${datadir}/acr/modules/ or from the current directory, called module-name.acr. no nested includes allowed, bestie, i don't make the rules. 🚫
  • NOP — No Operation Keyword. this keyword is only for debugging purposes and it's used internally by ACR. this command does nothing. literally nothing. slay, i guess 💅

💜 LANGUAGES 💜

all language keywords export a HAVE_LANG_xxx variable with value 0 or 1. and you can append ! to the language keyword to specify that the target language is required, meaning the script must die when the desired language isn't supported on the target machine. dramatic exit, we love to see it 💀

  • LANG_C[!] — ACR will look for a C compiler and sets CC, depends for implicit LANG_CPP.
  • LANG_V[!] — ACR will look for the V compiler and sets V and VFLAGS.
  • LANG_CC[!] LANG_CXX[!] — adds C++ support and sets CXX environ.
  • LANG_BASH[!] — tells acr to look for a bash on the target system.
  • LANG_TCL[!] — looks for tcl version and libraries. exports TCL_VERSION, TCL_CFLAGS and TCL_LDFLAGS to the environment. this will also add the --with-tcl-basedir flag so the end-user can set the basedir for the TCL installation. 🎀
  • LANG_PERL[!] — looks for perl installed on the current system.
  • LANG_JAVA[!] — looks for javac on the current system. exports JAVAC environ and adds --with-jikes and --with-kjc flags.
  • LANG_VALA[!] — looks for valac in PATH. exports VALAC environ and adds --with-valac.
  • LANG_PYTHON[!] — finds a python executable on the current system. exports PYTHON and HAVE_LANG_PYTHON.
  • LANG_RUBY[!] — finds a ruby executable on the current system. exports RUBY, HAVE_LANG_RUBY and RUBY_VERSION.

🔥 EXTERNAL SOFTWARE 🔥

  • USE_DL — sets LIBS_DL to -ldl or "" depending on the target system.
  • USE_LIBTOOL — checks for the libtool command and exports LIBTOOL_CC, LIBTOOL_CXX and some useful commands for your makefiles: LIBTOOL_SHARED, LIBTOOL_STATIC and LIBTOOL_INSTALL.
  • USE_PKGCONFIG | USE_PKGCONFIG! — checks for the pkg-config or pkgconf program in PATH. required for the PKGCFG directive.
  • USE_ICONV — sets LIBS_ICONV to -liconv or "", depending on whether iconv functions are implemented into the LibC or not.
  • USE_PTHREAD — checks for pthread on the current system and sets PTHREAD_LIBS to the proper value.
  • USE_PERL_THREADS — checks if the target system has perl built with threads support.
  • USE_X11 — adds --with-x11base and --without-x flags and sets X11BASE to the proper value.
  • USE_TK — adds the --with-tk-libdir flag and sets TK_CFLAGS, TK_VERSION.
  • USE_GMAKE — looks for a GNU make tool installed on the target system and sets MAKE properly.
  • USE_JNI — uses JAVA_HOME to check and define the JCFLAGS for building java native interface programs.

💖 CHECKS 💖

  • REQUIRE_ACR_VERSION version — checks if the acr version is greater or equal than the given version.
  • CHECK varname <<EOF <..src..> <<EOF — executes the <..code..> delimited by the <eof> keyword and marks varname as the target variable to be defined by the script. (see examples/check.acr fmi)
  • CHKEXE,CHECK_EXEC[!] varname program ; — executes program and sets varname = !!!$?
  • CHKPRG, CHECK_PROGRAM[!] varname program — finds the program in ${PATH} and sets the variable environment to the proper path. since 0.5 CHKPRG exports a HAVE_varname variable and checks first if VARNAME is a valid executable file.
  • CHKINC, CHECK_INCLUDE[!] include.h[+include2.h[+include3.h]] — checks if include.h is found in the current system. requires LANG_C and sets the HAVE_include_H environment to 0 or 1 (for example: HAVE_STDIO_H).
  • CHKFLG, CHECK_CFLAGS[!] varname cflags ; — checks if the selected C compiler supports the given CFLAGS. (useful for -std=c99 and such)
  • CHKFNC, CHECK_FUNCTION[!] libname function — checks if the desired function exists in libname and sets HAVE_FUNCTION to 0 or 1 (for example: HAVE_PRINTF).
  • CHKSYM, CHECK_SYMBOL[!] libname symbol — checks if the given symbol exists in libname and sets HAVE_SYMBOL to 0 or 1 (for example: HAVE_ENVIRON).
  • CHKDECL, CHECK_DECLARATION[!] include constant — checks if the given constant is defined in the specified include file.
  • CHKLIB, CHECK_LIBRARY[!] libname — checks if the desired library exists on the system and sets HAVE_LIB_libname to 0 or 1 (for example: HAVE_LIB_SDL).
  • ENDIAN|CHECK_ENDIAN — checks for the host endianness to be big or little. it'll export BYTEORDER=1234 on little endian hosts or 4321 for big endian ones. also exports LIL_ENDIAN and BIG_ENDIAN with 0 xor 1 values.
  • SIZEOF var ; — checks for the size of the desired variable and saves it into the variable SIZEOF_VARNAME. requires LANG_C.
  • CHECK_PERL_MODULE[!],CHK_PM[!] perl_module — checks if the target system has installed the selected perl module, and sets HAVE_PM_xxx to 0 or 1 (for example: HAVE_PM_NETDNS).
  • CHECK_PYTHON_MODULE[!],CHK_PY[!] python_module — checks if the system has installed the desired python module and sets HAVE_PY_xxx to 0 or 1.
  • CHECK_RUBY_EXTENSION[!],CHK_RU[] ruby_extension — checks if the system has installed the desired ruby extension and sets HAVE_RU_xxx to 0 or 1.
  • CHECK_CLASSPATH[!],CHK_CP[!] java_package_name — checks if CLASSPATH contains the desired package (for example org.gnu.gtk). exports the HAVE_CLASSPATH_(java-pkg-name) to 0 or 1.
  • CHKUSR[!] username
  • CHKGRP[!] group — checks the existence of the target user or group on the system. 🫶

🧠 DEFINITIONS 💅

okay so bestie, definitions get processed at the very beginning of the configure script — like, before anything else even wakes up. so these are your ground rules, set first, no takebacks. ✨

  • = varname value ; — sets the value of varname to value. just... assigns it. that's the whole vibe. 🎀
  • += varname value ; — appends value onto whatever varname already has, no erasing, just adding on. 🦋
  • ?= varname value ; — only if varname is empty does it get assigned value. like, if it's already got something, back off. conditional queen behavior. 💅
  • EXEC[!] variable command to execute ; — sets variable to the output (stdout) of the command you want executed. 📸
  • CHECK_VERSION,CHKVER[!] pkgname version — checks whether pkgname (a software package registered in the pkg-config database) is <= version. and if it's not? it crashes execution. dramatic, but okay. it exports the HAVE_(pkgname)_VERSION_(version) variable as 0 or 1. ✅
  • PKGCFG,PKGCONFIG[+] cflags_var ldflags_var pkg-config-name — uses pkg-config to grab the CFLAGS and LDFLAGS. if there's a '+' at the end of the command then ACR concatenates the value of cflags_var and ldflags_var instead of overwriting the old value. this keyword also exports a variable called HAVE_PKGFG_{pkg-config-name|filtered} with 0 or 1 values. ✨
  • PKGCFG_DO pcfile libname requires ; — generates a pkg-config file for the given library name and makes it depend on the word-separated list of pkg-config requires. optional overrides can be exported with PKGCFG_LIBS_DEFAULT, PKGCFG_LIBS_PRIVATE_DEFAULT, PKGCFG_CFLAGS_DEFAULT or the per-library PKGCFG_<LIBNAME>_{LIBS,LIBS_PRIVATE,CFLAGS} variables, where <LIBNAME> is the filtered upper-case form of libname. 💖
  • VALAPKG[!] pkgname — checks if a Vala package is available for VALAC. 🧚

🔀 CONDITIONALS 🌈

fr fr, all conditionals need an 'op' (operation) argument that tells ACR how to set the setvarname. the valid operations are:

  • '='
  • '+='
  • '?='

you can nest conditionals inside other conditionals using the '{' '}' keywords too! that lets you glue a whole group of conditionals and definitions together inside one block. nested conditionals have been a thing since acr 0.4. 👑

  • IF|IFNOT varname { ..code.. } — if the value of varname is equal to '1' (IF) or '0' (IFNOT), then ACR sets the 'setvarname' to the 'value'. 💫
  • IFNULL|IFNOTNULL varname { ..code.. } — if the value of varname is equal to null (IFNULL), or not (IFNOTNULL), then ACR sets the 'setvarname' to the 'value'. 🫶
  • IFEQ|IFNOTEQ varname value; { ..code.. } — if the content of varname is equal (IFEQ) or different (IFNOTEQ) to value, then set setvarname to the value setvalue. 🌸
  • IFEQVAL|IFNOTEQVAL varname varname2 { ..code.. } — DEPRECATED: this keyword has been deprecated in 0.5 and will disappear in 0.6. use IFEQ FOO $FOO ; instead. if the content of varname is equal (IFEQ) or different (IFNOTEQ) to the content of varname2, it finally sets setvarname to the value setvalue. 💀
  • IFAND|IFNOTAND var1 var2 { ..code.. } — if var1 and var2 are equal to 1 (IFAND) or 0 (IFNOTAND), then set var to setvalue. ✨
  • IFAND|IFNOTAND var1 var2 { ..code.. } — if var1 and var2 are equal to 1 (IFAND) or 0 (IFNOTAND), then set var to setvalue. (yes bestie, it's listed twice. i don't make the rules, i just translate them. 🙈)
  • IFOR|IFNOTOR var1 var2 { ..code.. } — if var1 and var2 are equal to 1 (IFAND) or 0 (IFNOTAND), then set var to setvalue.
  • ECHO string ; — prints a string to stderr. 📢
  • DIEIF|DIE variable die_message ; — 💅
  • DIEIFNOT|DIENOT variable die_message ; — 💅
  • DIENOW die_message ; — if the value of variable is equal to 1 (DIE) or 0 (DIENOT), then it stops processing the ./configure script and shows the die message. the short keyword names (DIE, DIENOT) are going to be deprecated. ⚠️

🚩 FLAGS 🚩

  • ARG_IGNORE flagname — ignores a specific configure arg. literally does nothing. it's giving "not my problem". 💅
  • ARG_[WITH|WITHOUT|ENABLE|DISABLE] varname[=value] flagname description ; — adds a with/without/enable/disable flag to the final configure script. for example:
ARG_WITH  MPLAYER=/usr/bin/mplayer mplayer Sets path for the mplayer ;

if no =value is given, ARG_* acts as a boolean variable (0 for WITH and ENABLE, and 1 for WITHOUT and DISABLE). if the =value is given, ACR lets the user construct flags like --with-foo=bar. 🔥

the 'value' argument must be one of these:

  • "" (empty) — if you want a true/false flag (ex: --without-x, --enable-ssl) 🎀
  • "=" — if you want the user to add their own value (ex: --with-x11base=/usr/pkg/XFree86/) 🦋
  • "something" — if you want to set the value to "something" when the flag is passed (ex: --with-kjc -> sets JAVAC to kjc) ✨

📝 OUTPUT GENERATION 💖

  • OUTPUT_H file1 file2 ; — generates file1 file2 with C-like syntax, #define-ing all the exported variables. 🧚
  • OUTPUT_SH file1 file2 ; — generates the selected files like OUTPUT_H does, but using a shellscript syntax instead. 🌸
  • SUBST|SUBST_FILES file1 file2 ; — replaces all @ENVWORDS@ with the exported variable's proper value. before making any changes, ACR copies the original file to file.orig. remember to mv file.orig file on the make clean target! this option is not recommended to use, because of the problems you may run into with acr + vcs systems. i recommend you use SUBDIRS instead. (acr>=0.4) 😭
  • SUBDIRS dir1 dir2 file1 file2 ; — finds Makefile.acr files in the requested directories to generate the proper Makefile. acr>=0.4 lets you use SUBDIRS against files or directories, with no difference — it's backward compatible. if the target name is a directory, then acr looks for Makefile.acr; if not, it grabs filename.acr and generates a new file keeping the name, but chopping off the '.acr' at the end. you can also use the '%' keyword to match all Makefile.acr files under the current directory — super handy if your project's directory structure keeps changing. 👑
  • SUBCONF dir1 dir2 ; — calls recursively other ./configure scripts found in dir1, dir2, passing along the root ./configure flag arguments. 🌈
  • REPORT var1 var2 ; — shows the varname and varvalue of the desired variables at the end of the final ./configure script. useful for debugging! 🐛

🌟 EXAMPLES 🌟

simple example:

PKGNAME helloworld

CONTACT my real name ; my@email.com

VERSION 1.0

LANG_C!

SUBDIRS . src ;

some more checks:

PKGNAME gtkapp

VERSION 1.0

LANG_C!

PKGCFG+ CFLAGS LDFLAGS gtk+-2.0

SUBDIRS . src ;

REPORT HAVE_PKGCFG_GTK_2_0 CFLAGS LDFLAGS ;

👀 SEE ALSO 🔍

acr(1) amr(1) acr-cat(1) configure.amr(5)

💜 AUTHOR 💜

pancake <pancake@nopcode.org>

http://nopcode.org/wk.php/Acr

and that's the whole page, bestie!! 🫶 this one comes to you from Debian, dated Feb 25, 2022, and it's the CONFIGURE.ACR(5) manual page — so if you ever need the receipts, that's where they live. now go write a configure.acr that slays. periodt. 💅✨🎀

📦 where this page comes from