Skip to main content

​
Overview

OmniView is built with Go 1.24 and uses CGO for Oracle ODPI-C integration. This guide covers everything you need to build the project from source.

​
Prerequisites

​
Required Software

Before building OmniView, ensure you have the following installed:

Go 1.24+

Go programming language with CGO support enabled

Oracle Instant Client

Version 23.7 or later with SDK package

C Compiler

GCC (Linux/macOS) or MinGW-w64 (Windows)

Git

For cloning the repository

​
Platform-Specific Requirements

# Install build essentials
sudo apt-get update
sudo apt-get install build-essential git

# Install Go 1.24
wget https://go.dev/dl/go1.24.linux-amd64.tar.gz
sudo tar -C /usr/local -xzf go1.24.linux-amd64.tar.gz
export PATH=$PATH:/usr/local/go/bin

​
Oracle Instant Client Setup

OmniView requires Oracle Instant Client with the SDK package. 
# Download and install to /opt/oracle/
export INSTANT_CLIENT_DIR=/opt/oracle/instantclient_23_7
Make sure to download both the Basic package and SDK package from Oracle’s website. The SDK package is required for building.

​
Cloning the Repository

Clone the OmniView repository from your source control: 
git clone <repository-url> omniview
cd omniview

​
Installing Dependencies

OmniView uses Go modules for dependency management. Install all dependencies: 
make install
The make install target runs:
  • go mod download - Downloads all Go dependencies
  • go mod tidy - Cleans up unused dependencies
Output:
[INSTALL] Installing Go dependencies...
go: downloading github.com/google/uuid v1.6.0
go: downloading go.etcd.io/bbolt v1.4.3
go: downloading golang.org/x/sys v0.29.0
[OK] Dependencies installed

​
Key Dependencies

From go.mod: 
require (
    github.com/google/uuid v1.6.0    // UUID generation
    go.etcd.io/bbolt v1.4.3          // Embedded database
)

​
Building the Project

​
Standard Build

Build the complete project with a single command: 
make build

[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
[OK] Build complete: omniview (dev)
The build process automatically:
  1. Checks and builds the ODPI-C library (if needed)
  2. Sets CGO compiler and linker flags
  3. Compiles the Go application
  4. Links the CGO modules (dequeue_ops.c)

​
Building with Version Number

Specify a version during build: 
make build VERSION=v1.2.0
The version is embedded in the binary at internal/app.Version using Go build flags.

​
Build Output

Successful build produces:
  • omniview (or omniview.exe on Windows) - Main executable
  • third_party/odpi/lib/libodpi.dylib (macOS) or odpi.dll (Windows) - ODPI library

​
Running Tests

Run the test suite: 
make test
Output: 
[TEST] Running tests...
go test -v ./...
?       OmniView/cmd/omniview   [no test files]
?       OmniView/internal/app   [no test files]

​
Development Workflow

​
Quick Development Cycle

  1. Make changes to source code
  2. Format code: make fmt
  3. Lint code: make lint
  4. Build and run: make run

​
Common Development Commands

Format Code

make fmt
Formats all Go code using go fmt

Lint Code

make lint
Runs go vet to check for issues

Clean Build

make clean
make build
Removes artifacts and rebuilds

Debug CGO

make check-cgo
Shows CGO compilation details

​
Build and Run

Build and immediately run the application: 
make run
This target:
  1. Builds the project (including dependencies)
  2. Executes the binary with appropriate platform handling

​
Debugging CGO Compilation

If you encounter CGO issues, use the debug target: 
make check-cgo
This shows:
  • CGO compiler flags being used
  • CGO linker flags being used
  • Detailed GCC/Clang compilation steps
  • Which files are being compiled by CGO
[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:
gcc -I. -fPIC -arch arm64 -I/Users/dev/omniview/third_party/odpi/include ...

Building oracle storage package with debug output:
gcc -I. -fPIC -arch arm64 ... dequeue_ops.c ...

​
Cleaning Build Artifacts

Remove all build artifacts and caches: 
make clean
This removes:
  • Compiled ODPI object files (third_party/odpi/build/)
  • ODPI source files (if any)
  • Binary executables (omniview, omniview.exe)
  • Database files (*.db)
  • Go build cache

​
Troubleshooting

​
CGO Compiler Not Found

Error: cgo: C compiler "gcc" not foundSolution: Install a C compiler:
  • Linux: sudo apt-get install build-essential
  • macOS: xcode-select --install
  • Windows: Install MinGW-w64 or use Git Bash

​
Oracle Instant Client Not Found

Error: ld: library not found for -lclntshSolution: Set the INSTANT_CLIENT_DIR environment variable or update it in the Makefile:
# macOS/Linux
export INSTANT_CLIENT_DIR=/path/to/instantclient

# Windows
set INSTANT_CLIENT_DIR=C:\path\to\instantclient

​
Go Version Mismatch

Error: go.mod requires go >= 1.24Solution: Update to Go 1.24:
go version  # Check current version
# Download and install Go 1.24 from https://go.dev/dl/

​
ODPI Build Fails

If the ODPI library fails to build, try building it separately: 
make odpi
Check that:
  • Oracle Instant Client SDK is installed
  • INSTANT_CLIENT_DIR points to the correct location
  • SDK include files exist at $INSTANT_CLIENT_DIR/sdk/include

​
Next Steps

Makefile Reference

Learn about all available make targets

CGO Integration

Deep dive into CGO and ODPI-C integration

Build docs developers (and LLMs) love

Get started for freeTalk to us