Makefile Reference

Overview

OmniView’s Makefile provides a comprehensive build system with automatic OS detection, ODPI-C library compilation, and cross-platform support. The Makefile is 277 lines and handles Windows, macOS, and Linux builds.

Architecture

The Makefile is organized into several sections:

OS Detection - Automatic platform and shell detection
ODPI-C Configuration - Oracle library build settings
Go Build Configuration - CGO flags and version management
Build Targets - All available make commands
Release Packaging - Platform-specific distribution bundles

Quick Reference

make build

Build the application (default)

make run

Build and run OmniView

make test

Run test suite

make clean

Remove build artifacts

make release

Create distribution package

make odpi

Build ODPI-C library only

OS Detection

The Makefile automatically detects the operating system and shell environment:

ifeq ($(OS),Windows_NT)
    DETECTED_OS := Windows
else
    UNAME_S := $(shell uname -s)
    ifeq ($(UNAME_S),Darwin)
        DETECTED_OS := MacOS
    else
        DETECTED_OS := $(UNAME_S)
    endif
endif

Windows Shell Detection

On Windows, the Makefile detects whether you’re using Bash (Git Bash, MSYS2, WSL) or native cmd.exe:

# Sets USE_BASH=1 for bash-like shells
# Sets USE_BASH=0 for cmd.exe/PowerShell
SHELL_TYPE := $(shell echo $$0)

This allows the Makefile to use the correct commands (mkdir -p vs mkdir, cp vs copy, etc.).

Build Configuration

Version Flag

Specify a version number during build:

make build VERSION=v1.2.0

The version is embedded using Go linker flags:

VERSION ?= dev
GO_LDFLAGS = -ldflags "-X OmniView/internal/app.Version=$(VERSION)"

CGO Flags

The Makefile exports CGO flags that Go automatically picks up during compilation:

macOS
Windows
Linux

export CGO_CFLAGS = -I$(PWD)/third_party/odpi/include
export CGO_LDFLAGS = -L$(PWD)/third_party/odpi/lib -lodpi \
    -Wl,-rpath,$(PWD)/third_party/odpi/lib \
    -Wl,-rpath,$(INSTANT_CLIENT_DIR)

export CGO_CFLAGS = -I$(PWD)/third_party/odpi/include
export CGO_LDFLAGS = -L$(PWD)/third_party/odpi/lib -lodpi \
    -L$(INSTANT_CLIENT_DIR) -loci

export CGO_CFLAGS = -I$(PWD)/third_party/odpi/include
export CGO_LDFLAGS = -L$(PWD)/third_party/odpi/lib -lodpi \
    -Wl,-rpath,$(PWD)/third_party/odpi/lib

Build Targets

make build

Default target - Builds the complete OmniView application.

make build
make build VERSION=v1.0.0  # With version

Build process steps

Checks if ODPI library exists (builds if missing via deps target)
Exports CGO compiler and linker flags
Runs go build with version flags
Compiles CGO files (dequeue_ops.c) automatically
Links everything into final binary

Output:

[INFO] Checking dependencies...
[OK] All dependencies ready
[BUILD] Building omniview (version: dev)...
   CGO_CFLAGS=-I/home/user/omniview/third_party/odpi/include
   CGO_LDFLAGS=-L/home/user/omniview/third_party/odpi/lib -lodpi -Wl,-rpath,/home/user/omniview/third_party/odpi/lib -Wl,-rpath,/opt/oracle/instantclient_23_7
go build -v -ldflags "-X OmniView/internal/app.Version=dev" -o omniview ./cmd/omniview
OmniView/internal/adapter/storage/oracle
OmniView/internal/adapter/subscription
OmniView/cmd/omniview
[OK] Build complete: omniview (dev)

Source:

.PHONY: build
build: deps
	@echo "[BUILD] Building $(BINARY_NAME) (version: $(VERSION))..."
	@echo "   CGO_CFLAGS=$(CGO_CFLAGS)"
	@echo "   CGO_LDFLAGS=$(CGO_LDFLAGS)"
	go build -v $(GO_LDFLAGS) -o $(BINARY_NAME) ./$(MAIN_PATH)
	@echo "[OK] Build complete: $(BINARY_NAME) ($(VERSION))"

make odpi

Builds only the ODPI-C library without building the Go application.

make odpi

ODPI build details

The ODPI library is built from source files in third_party/odpi/:

Compiles all .c files in third_party/odpi/src/ to .o object files
Links object files into a shared library:
- macOS: libodpi.dylib (ARM64 architecture)
- Windows: odpi.dll
Copies library to third_party/odpi/lib/
On Windows, copies DLL to workspace root

Platform-specific settings:macOS:

LDFLAGS = -dynamiclib -arch arm64 \
    -install_name @rpath/libodpi.dylib \
    -Wl,-rpath,$(INSTANT_CLIENT_DIR)
CFLAGS = -O2 -Wall -I$(INSTANT_CLIENT_SDK)/include -arch arm64
TARGET = third_party/odpi/lib/libodpi.dylib
LIBS = -L$(INSTANT_CLIENT_DIR) -lclntsh

Windows:

LDFLAGS = -shared
CFLAGS = -O2 -Wall -I$(INSTANT_CLIENT_SDK)/include
TARGET = third_party/odpi/lib/odpi.dll
LIBS = -L$(INSTANT_CLIENT_DIR) -loci

make run

Builds and immediately runs the application.

make run

Dependency chain: run → build → deps → odpi Output:

[BUILD] Building omniview (version: dev)...
[OK] Build complete: omniview (dev)
[RUN] Running omniview...

make test

Runs the Go test suite.

make test

Source:

.PHONY: test
test:
	@echo "[TEST] Running tests..."
	go test -v ./...

Example output:

[TEST] Running tests...
go test -v ./...
?       OmniView/cmd/omniview                           [no test files]
?       OmniView/internal/adapter/storage/oracle        [no test files]
=== RUN   TestSomething
--- PASS: TestSomething (0.01s)
PASS
ok      OmniView/internal/adapter    0.123s

make deps

Checks and builds all dependencies (primarily the ODPI library).

make deps

This target is automatically called by make build. Source:

.PHONY: deps
deps: $(TARGET)
	@echo "[INFO] Checking dependencies..."
	@echo "[OK] All dependencies ready"

make install

Installs and tidies Go module dependencies.

make install

Output:

[INSTALL] Installing Go dependencies...
go mod download
go mod tidy
[OK] Dependencies installed

make fmt

Formats all Go source code using go fmt.

make fmt

Output:

[FMT] Formatting code...
go fmt ./...
internal/adapter/storage/oracle/oracle.go
internal/app/app.go
[OK] Format complete

make lint

Runs go vet to check for common coding issues.

make lint

Output:

[LINT] Linting code...
go vet ./...
[OK] Lint complete

make check-cgo

Debug target that shows detailed CGO compilation information.

make check-cgo

Example output

[DEBUG] Checking CGO compilation...
CGO_CFLAGS=-I/Users/dev/omniview/third_party/odpi/include
CGO_LDFLAGS=-L/Users/dev/omniview/third_party/odpi/lib -lodpi -Wl,-rpath,/Users/dev/omniview/third_party/odpi/lib -Wl,-rpath,/opt/oracle/instantclient_23_7

Building subscription package with debug output:
cd /Users/dev/omniview/internal/adapter/subscription
gcc -I. -fPIC -arch arm64 -pthread -fno-caret-diagnostics -Qunused-arguments \
    -I/Users/dev/omniview/third_party/odpi/include \
    -o $WORK/queue_callback.o -c queue_callback.c

Building oracle storage package with debug output:
cd /Users/dev/omniview/internal/adapter/storage/oracle
gcc -I. -fPIC -arch arm64 -pthread -fno-caret-diagnostics -Qunused-arguments \
    -I/Users/dev/omniview/third_party/odpi/include \
    -o $WORK/dequeue_ops.o -c dequeue_ops.c

make clean

Removes all build artifacts and caches.

make clean

Deletes:

ODPI build artifacts (third_party/odpi/build/)
ODPI source artifacts (third_party/odpi/src/)
Binary executables (omniview, omniview.exe, odpi.dll)
Database files (*.db)
Go build cache

Output:

[CLEAN] Cleaning build artifacts...
go clean -cache
[OK] Clean complete

Release Packaging

make release

Creates a platform-specific distribution archive.

make release VERSION=v1.2.0

Always specify a VERSION when creating releases. The default “dev” version should not be used for distributions.

macOS
Windows

Creates: omniview-darwin-arm64-v1.2.0.tar.gzContents:

omniview - Main binary (ARM64)
libodpi.dylib - ODPI library

Process:

Builds the application
Creates temporary release/ directory
Copies binary and library
Creates tar.gz archive
Removes temporary directory

Output:

[RELEASE] Packaging release v1.2.0...
[RELEASE] Creating macOS arm64 archive...
[OK] Created omniview-darwin-arm64-v1.2.0.tar.gz

Creates: omniview-windows-amd64-v1.2.0.zipContents:

omniview.exe - Main executable
odpi.dll - ODPI library

Process:

Builds the application
Creates temporary release/ directory
Copies executable and DLL
Creates ZIP archive (using zip or PowerShell)
Removes temporary directory

Output:

[RELEASE] Packaging release v1.2.0...
[RELEASE] Creating Windows amd64 archive...
[OK] Created omniview-windows-amd64-v1.2.0.zip

Source (macOS):

release: build
	@echo "[RELEASE] Packaging release $(VERSION)..."
	@echo "[RELEASE] Creating macOS arm64 archive..."
	@mkdir -p release
	@cp $(BINARY_NAME) release/
	@cp $(ODPI_BASE)/lib/libodpi.dylib release/ 2>/dev/null || true
	@tar -czf omniview-darwin-arm64-$(VERSION).tar.gz -C release .
	@rm -rf release
	@echo "[OK] Created omniview-darwin-arm64-$(VERSION).tar.gz"

make help

Shows all available Makefile targets with brief descriptions.

make help

Output:

OmniInspect Makefile - Available targets:

  make build                  - Build the Go application (default)
  make build VERSION=v1.0.0   - Build with specific version
  make run                    - Build and run the application
  make release VERSION=v1.0.0 - Build and package for distribution
  make odpi                   - Build only ODPI-C library
  make deps                   - Check/build dependencies
  make clean                  - Remove all build artifacts
  make test                   - Run tests
  make check-cgo              - Debug CGO compilation
  make install                - Install Go dependencies
  make fmt                    - Format Go code
  make lint                   - Lint Go code
  make help                   - Show this help message

Use make help anytime to see the complete list of available targets.

Environment Variables

Customize the build by setting environment variables:

INSTANT_CLIENT_DIR

Specifies the Oracle Instant Client installation directory.

export INSTANT_CLIENT_DIR=/opt/oracle/instantclient_23_7
make build

Default values:

macOS/Linux: /opt/oracle/instantclient_23_7
Windows: C:/oracle_inst/instantclient_23_7

VERSION

Sets the application version embedded in the binary.

make build VERSION=v1.2.0
make release VERSION=v1.2.0

Default: dev

Platform-Specific Builds

macOS (ARM64)

The Makefile builds native ARM64 binaries for Apple Silicon:

CFLAGS = -O2 -Wall $(INCLUDE) -I$(INSTANT_CLIENT_INCLUDE) -arch arm64
LDFLAGS = -dynamiclib -arch arm64 \
    -install_name @rpath/libodpi.dylib \
    -Wl,-rpath,$(INSTANT_CLIENT_DIR)

The -arch arm64 flag ensures native Apple Silicon compilation. For Intel Macs, you would need to modify this to -arch x86_64.

Windows Shell Support

The Makefile works with multiple Windows shell environments:

Git Bash / MSYS2

Uses Unix-style commands:

mkdir -p
cp -f
rm -rf

cmd.exe / PowerShell

Uses native Windows commands:

mkdir
copy /Y
rmdir /s /q

Build Workflow Example

Complete workflow for building and releasing:

# 1. Clone and setup
git clone <repo-url> omniview
cd omniview

# 2. Install dependencies
make install

# 3. Build ODPI library
make odpi

# 4. Build application
make build

# 5. Run tests
make test

# 6. Format and lint
make fmt
make lint

# 7. Create release
make release VERSION=v1.0.0

# 8. Clean up
make clean

Troubleshooting

Build Fails with CGO Error

# Check CGO configuration
make check-cgo

# Verify ODPI library
ls -la third_party/odpi/lib/

# Rebuild ODPI
make clean
make odpi

Oracle Library Not Found

If you see library not found errors, verify:

Oracle Instant Client is installed
INSTANT_CLIENT_DIR is set correctly
The SDK package is installed (not just Basic)

# Check Instant Client
echo $INSTANT_CLIENT_DIR
ls -la $INSTANT_CLIENT_DIR/sdk/include/

Windows DLL Copy Fails

If odpi.dll isn’t found at runtime:

# Manually copy DLL to workspace root
cp third_party/odpi/lib/odpi.dll .

# Or add to PATH
set PATH=%PATH%;%CD%\third_party\odpi\lib

Getting Started

Core Concepts

Usage Guide

Development

​Overview

​Architecture

​Quick Reference

make build

make run

make test

make clean

make release

make odpi

​OS Detection

​Windows Shell Detection

​Build Configuration

​Version Flag

​CGO Flags

​Build Targets

​make build

​make odpi

​make run

​make test

​make deps

​make install

​make fmt

​make lint

​make check-cgo

​make clean

​Release Packaging

​make release

​make help

​Environment Variables

​INSTANT_CLIENT_DIR

​VERSION

​Platform-Specific Builds

​macOS (ARM64)

​Windows Shell Support

Git Bash / MSYS2

cmd.exe / PowerShell

​Build Workflow Example

​Troubleshooting

​Build Fails with CGO Error

​Oracle Library Not Found

​Windows DLL Copy Fails

​Next Steps

Building from Source

CGO Integration

Build docs developers (and LLMs) love

Overview

Architecture

Quick Reference

OS Detection

Windows Shell Detection

Build Configuration

Version Flag

CGO Flags

Build Targets

make build

make odpi

make run

make test

make deps

make install

make fmt

make lint

make check-cgo

make clean

Release Packaging

make release

make help

Environment Variables

INSTANT_CLIENT_DIR

VERSION

Platform-Specific Builds

macOS (ARM64)

Windows Shell Support

Build Workflow Example

Troubleshooting

Build Fails with CGO Error

Oracle Library Not Found

Windows DLL Copy Fails

Next Steps