getting-started.md

Getting Started

Installation

Homebrew (macOS):

brew tap wess/goose
brew install goose

Shell script:

curl -fsSL https://raw.githubusercontent.com/wess/goose/main/install.sh | sh

Custom install directory:

GOOSE_INSTALL_DIR=~/.local curl -fsSL https://raw.githubusercontent.com/wess/goose/main/install.sh | sh

asdf:

asdf plugin add goose https://github.com/wess/goose.git
asdf install goose latest
asdf global goose latest

Build from source:

git clone https://github.com/wess/goose.git
cd goose
make
make install  # installs to /usr/local

To install to a custom location:

make install PREFIX=~/.local

To uninstall:

make uninstall

Creating Your First Project

goose new hello
cd hello

This creates the following structure:

hello/
  goose.yaml
  src/
    main.c
  .gitignore

Building and Running

goose build        # debug build  -> build/debug/hello
goose build -r     # release build -> build/release/hello
goose run          # build + run (debug)
goose run -r       # build + run (release)

The goose.yaml File

Every goose project has a goose.yaml at its root:

project:
  name: "hello"
  version: "0.1.0"
  description: "My first goose project"
  author: "Your Name"
  license: "MIT"

build:
  cc: "cc"
  cflags: "-Wall -Wextra -std=c11"
  includes:
    - "src"

dependencies:

Adding a Dependency

Dependencies are git repositories or local paths:

goose add https://github.com/user/somelib.git

This clones the repo into packages/somelib/, adds it to goose.yaml, and records the exact commit in goose.lock.

You can specify a name and version tag:

goose add https://github.com/user/somelib.git --name mylib --version v1.0.0

Then include its headers in your code:

#include <somelib.h>

Running Tests

Create a tests/ directory with .c files. Each test file must have its own main():

// tests/basic.c
#include <assert.h>
#include <stdio.h>

int main(void) {
    assert(1 + 1 == 2);
    printf("passed\n");
    return 0;  // 0 = pass, non-zero = fail
}

Run all tests:

goose test

Cleaning Up

goose clean  # removes build/ directory

Next Steps

• Read the Configuration Reference for all goose.yaml options
• Read Dependencies to learn about package management
• Read Creating Packages to publish your own library
• Read Plugins to use custom transpilers (flex, bison, etc.)
• Read Using libgoose.a to embed goose in your own tools
• See the examples/ directory for working examples