Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/fernandodanielmaqueda/gcc-bison-flex-GNUmakefile/llms.txt

Use this file to discover all available pages before exploring further.

The framework generates a dedicated set of execution targets for every program listed in BIN_PROGRAMS. These targets let you run, debug with GDB, or analyze with Valgrind — all from the same make invocation that built the project, with consistent working directory and argument handling.

​
run-<program> targets

For each program named <program> in BIN_PROGRAMS, the framework generates a .PHONY target called run-<program>. The target:
  1. Checks that the program binary exists (exits with an error if it has not been built yet).
  2. Changes to $(program)_CWD if it is set.
  3. Executes the program using its absolute path, passing $(program)_ARGS as arguments.
  4. Returns to the previous directory.
make run-myprogram
Override $(program)_ARGS directly on the make invocation:
make run-myprogram myprogram_ARGS="--input file.txt --verbose"
You can also set the variable permanently in your project Makefile:
myprogram_ARGS:=--input file.txt --verbose
By default $(program)_CWD is set to $(BINDIR) (i.e., bin/), so the program runs from the output directory. To change it:
# Run from a specific directory
myprogram_CWD:=/path/to/data

# Run from the current directory (where make is invoked)
myprogram_CWD:=
When $(program)_CWD is empty the framework skips the cd step entirely and runs the program directly in the current working directory.
If the binary does not exist, the target prints an error and exits with a non-zero status:
EXCEPTION: program does not exist: "bin/myprogram". It must be built first...
Build it first with make all, then run it.

​
gdb-<program> targets

For each program in BIN_PROGRAMS, the framework generates a gdb-<program> target that launches GDB with the program already loaded. 
make gdb-myprogram
The target invokes: 
gdb $(GDBFLAGS) '<absolute path to program>' $(myprogram_ARGS)
GDB is treated as an indispensable command: if it is not found on PATH, Make reports the error and stops before attempting to run any recipe.
GDBFLAGS is empty by default. Add options in your Makefile or on the command line:
make gdb-myprogram GDBFLAGS="-tui"
Once GDB loads, you have the full interactive CLI available:
(gdb) break main
(gdb) run
(gdb) next
(gdb) print variable_name
(gdb) backtrace
(gdb) quit
For meaningful GDB output you need debug symbols compiled in. CC_DEBUG is enabled by default (CC_DEBUG=X), which adds -g3 to CFLAGS and -DDEBUG=1 to CPPFLAGS. If you previously disabled it, re-enable it and rebuild:
make clean && make all CC_DEBUG=X
-g3 includes macro definitions in the debug information, making it possible to inspect preprocessor macros from inside GDB.
gdb-<program> respects the same $(program)_CWD and $(program)_ARGS variables as run-<program>. Arguments passed via $(program)_ARGS are forwarded to GDB so it can pass them to the inferior process when you run it.

​
valgrind-<tool>-<program> targets

The framework generates a target for every combination of tool in VALGRIND_TOOLS and program in BIN_PROGRAMS. The default VALGRIND_TOOLS are none memcheck helgrind, giving you three targets per program out of the box. 
make valgrind-memcheck-myprogram
The target invokes: 
valgrind $(VALGRIND_FLAGS) --tool=<tool> $(VALGRIND_<TOOL>_FLAGS) \
  '<absolute path to program>' $(myprogram_ARGS)
Valgrind is treated as an indispensable command in the same way as GDB.
Runs Valgrind without specifying a tool, which defaults to Valgrind’s built-in memcheck tool but without any additional per-tool flags from the framework.VALGRIND_NONE_FLAGS is empty by default.
make valgrind-none-myprogram
Runs the memcheck tool with the default flags:
VALGRIND_MEMCHECK_FLAGS=--leak-check=full --track-origins=yes
  • --leak-check=full — reports each individual leaked block with a full stack trace.
  • --track-origins=yes — traces the origin of uninitialized values, at the cost of extra runtime overhead.
make valgrind-memcheck-myprogram
Runs the helgrind tool, which detects threading errors such as data races, misuses of POSIX thread primitives, and lock ordering violations.VALGRIND_HELGRIND_FLAGS is empty by default. Add flags as needed:
VALGRIND_HELGRIND_FLAGS=--history-level=full

make valgrind-helgrind-myprogram
VALGRIND_FLAGS is applied to every Valgrind invocation regardless of tool. The default is --verbose. You can extend or replace it:
make valgrind-memcheck-myprogram VALGRIND_FLAGS="--verbose --error-exitcode=1"
Add tool names to VALGRIND_TOOLS before the framework footer is evaluated. The framework will generate targets and look for a matching VALGRIND_<TOOL>_FLAGS variable:
VALGRIND_TOOLS+=cachegrind massif

VALGRIND_CACHEGRIND_FLAGS=--cache-sim=yes --branch-sim=yes
VALGRIND_MASSIF_FLAGS=--pages-as-heap=yes
After adding tools, make valgrind-cachegrind-myprogram and make valgrind-massif-myprogram become available.
Other available Valgrind tools include: cachegrind, callgrind, drd, massif, dhat, lackey, exp-bbv.
Valgrind works best when the program includes full debug information. Build with CC_DEBUG=X (the default) to include -g3. Without debug symbols, Valgrind cannot show source file names and line numbers in its reports.
make clean && make all
make valgrind-memcheck-myprogram

​
Configuring execution for all targets

The _ARGS and _CWD variables work the same way across run-, gdb-, and valgrind- targets.
In your project Makefile, set program-specific arguments before the framework footer:
myprogram_ARGS:=--input data/test.txt --mode fast
Or pass them on the command line for a one-off run:
make run-myprogram myprogram_ARGS="--help"
make gdb-myprogram myprogram_ARGS="--mode debug"
make valgrind-memcheck-myprogram myprogram_ARGS="--input data/test.txt"

# Default: run from the bin/ output directory
myprogram_CWD:=$(BINDIR)

# Run from a specific data directory
myprogram_CWD:=data/

# Run from the directory where make was invoked
myprogram_CWD:=
An empty _CWD means no cd is performed — the program runs in whatever directory make was invoked from.

Build docs developers (and LLMs) love

Get started for freeTalk to us