Makefile¶

A Makefile is a simple text file used by the make build automation tool to manage dependencies and automate the compilation of programs. It defines a set of rules to follow in order to compile and link the program. The make tool uses these rules to decide how to build and update executables, libraries, and other files in a project.

Basic Structure¶

A Makefile consists of:

  1. Targets – The files that need to be created.

  2. Dependencies – The files that a target depends on.

  3. Commands – The shell commands that make will run to create the target.

General Syntax:¶

target: dependencies
    command

  • target: The file to be created or updated (often the executable or object files).

  • dependencies: Files that are required to build the target.

  • command: A shell command to execute. Commands are usually preceded by a tab (not spaces).

This project uses two Makefiles for different purposes:

  1. Project Root Makefile (Makefile)

    • Used to install essential dependencies for development.

    • Handles basic setup tasks.

    • Primarily serves as a bootstrap for initializing the development environment.

  2. Documentation Makefile (docs/Makefile)

    • Auto-generated by the sphinx-quickstart command.

    • Used for building project documentation.

    • Should not be called directly; instead, use the just file to execute documentation-related commands.

Usage¶

The primary Makefile in the root directory is used to set up the development environment. Typical commands include:

make check   		# To check system requirements
make install-just	# To print the install command for tool 'just'
make install-just-force	# To forcibly install the 'just' command runner
make install-uv     	# To print the install command for tool 'uv'
make install-uv-force	# To forcibly install the 'uv' tool

Force Installing Core Dependencies¶

If you encounter issues with just or uv, or if you want to ensure you have the very latest version, you can use the force variants of the installation commands:

  • make install-just-force: This command runs the official just installation script. It will install just to ~/bin and automatically add this directory to your PATH in ~/.zshenv if it’s not already there.

  • make install-uv-force: Similarly, this command runs the official uv installation script. It will install uv and ensure it’s properly configured in your environment.

These commands are part of the main Makefile in the project root, designed to help bootstrap your development environment. After running any installation command, especially a force install, ensure the tool’s installation directory (e.g., ~/bin for just, ~/.local/bin for uv) is correctly configured in your system’s PATH.

Additional Resources¶

For more details on how Makefiles work, refer to the GNU Make Manual.