libsodium-builder

** Automated multi-platform build system for libsodium static libraries**

A batteries-included shell script that automates the compilation of libsodium static libraries for WebAssembly, macOS, Linux, Windows, Android, and iOS with proper cross-compilation support.

Why This Script?

Building libsodium for multiple platforms can be tedious and error-prone:

Different build configurations for each platform
Complex cross-compilation toolchain setup
Manual universal binary creation
Inconsistent build flags across platforms

This script solves all of that:

One command to build for any platform
Automatic toolchain detection and configuration
Tested build configurations that just work
Reproducible builds with version pinning
Distribution-ready packages with checksums

Features

Feature	Description
Interactive Menu	User-friendly TUI for easy platform selection
Parallel Builds	Auto-detects CPU cores for faster compilation
Version Control	Build any git tag, branch, or commit
Universal Binaries	macOS and iOS fat binaries automatically created
XCFramework	Ready-to-use iOS framework with SPM support
Automated Testing	Runs libsodium test suite on native builds
SHA256 Checksums	Verify integrity of built libraries
Build Logs	Detailed logging with color-coded output
Smart Caching	ccache support for faster rebuilds
Distribution Packages	Auto-generated tar.gz archives

Supported Platforms

Platform	Architectures	Notes
WebAssembly	wasm32	Via Emscripten
macOS	x86_64 + arm64	Universal binary
Linux	x86_64, aarch64, etc.	Auto-detected
Windows	x86_64	MinGW cross-compile
Android	armv7, arm64, x86, x86_64	API 19+ (32-bit), 21+ (64-bit)
iOS	Device: arm64 Simulator: arm64 + x86_64	XCFramework included

Quick Start

# Clone this repository
git clone https://github.com/toprakdeviren/libsodium-builder.git
cd libsodium-builder

# Make script executable
chmod +x build-libsodium.sh

# Build for your current platform
./build-libsodium.sh macos

# Or use interactive mode
./build-libsodium.sh

That's it! Your static libraries will be in the dist/ directory.

Prerequisites

Required for All Builds

Git - Clone libsodium repository
Build Tools - autoconf, automake, libtool
Compiler - GCC, Clang, or platform-specific toolchain

macOS

# Install via Homebrew
brew install autoconf automake libtool pkg-config

Linux (Debian/Ubuntu)

sudo apt-get update
sudo apt-get install -y autoconf automake libtool pkg-config build-essential

Linux (RHEL/CentOS/Fedora)

sudo yum install -y autoconf automake libtool pkgconfig gcc gcc-c++ make

Platform-Specific Requirements

WebAssembly (Emscripten)

Install the Emscripten SDK:

# Clone and install
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install latest
./emsdk activate latest

# Activate for current shell
source ./emsdk_env.sh

Windows (MinGW Cross-Compilation)

Install MinGW-w64 on your build host:

# macOS
brew install mingw-w64

# Linux (Debian/Ubuntu)
sudo apt-get install mingw-w64

# Linux (RHEL/Fedora)
sudo yum install mingw-w64-gcc mingw-w64-gcc-c++

Note: For native Windows builds with MSVC, use official libsodium builds or CMake.

Android

Download the Android NDK
Extract and set environment variable:

export ANDROID_NDK_HOME=/path/to/android-ndk-r25c
# OR
export NDK_ROOT=/path/to/android-ndk-r25c

Add to your ~/.bashrc or ~/.zshrc for persistence.

iOS

Requires macOS with Xcode:

# Install Xcode from App Store, then:
xcode-select --install

# Verify installation
xcodebuild -version

Installation

Option 1: Clone Repository

git clone https://github.com/toprakdeviren/libsodium-builder.git
cd libsodium-builder
chmod +x build-libsodium.sh

Option 2: Direct Download

curl -O https://raw.githubusercontent.com/toprakdeviren/libsodium-builder/main/build-libsodium.sh
chmod +x build-libsodium.sh

Option 3: Add to PATH

# After cloning/downloading
sudo ln -s $(pwd)/build-libsodium.sh /usr/local/bin/build-libsodium
build-libsodium --help

Usage

Interactive Mode

Simply run the script without arguments:

./build-libsodium.sh

You'll see a friendly menu:

╔════════════════════════════════════════╗
║   libsodium Static Library Builder    ║
║          v1.0.0                        ║
╚════════════════════════════════════════╝
Select an option:
  1)  Build for WebAssembly
  2)  Build for macOS (Universal)
  3)  Build for Linux
  4)  Build for Windows (MinGW)
  5)  Build for Android (All ABIs)
  6)  Build for iOS (Device + Simulator + XCFramework)
  7)  Build for ALL platforms
  8)  Clean all
  9)  Exit

Command Line Mode

./build-libsodium.sh [COMMAND] [OPTIONS]

Commands

Command	Description
`wasm`	Build WebAssembly static library
`macos`	Build macOS universal binary (x86_64 + arm64)
`linux`	Build Linux static library (auto-detected arch)
`windows`	Build Windows static library (MinGW x86_64)
`android`	Build Android libraries for all ABIs
`ios`	Build iOS libraries + XCFramework
`all`	Build for all supported platforms
`clean`	Remove all build artifacts and source
`help`	Display help message

Options

Option	Description	Default
`--version <tag>`	Git tag, branch, or commit to build	`stable`
`--jobs <N>`	Number of parallel build jobs	Auto-detected
`--prefix <dir>`	Custom output directory	`./dist`
`-y, --yes`	Skip all confirmations (CI mode)	Interactive

Examples

Basic Usage

# Build for current platform (auto-detected)
./build-libsodium.sh linux

# Build for macOS with universal binary
./build-libsodium.sh macos

# Build all platforms
./build-libsodium.sh all

Version Control

# Build specific stable release
./build-libsodium.sh macos --version 1.0.18

# Build from specific branch
./build-libsodium.sh linux --version stable

# Build from specific commit
./build-libsodium.sh android --version a1b2c3d

Performance Tuning

# Use 8 parallel jobs
./build-libsodium.sh linux --jobs 8

# Enable verbose output
DEBUG=1 ./build-libsodium.sh macos

# Use ccache for faster rebuilds (if installed)
./build-libsodium.sh all  # Automatically detected

Custom Configuration

# Custom output directory
./build-libsodium.sh macos --prefix /opt/libsodium

# Custom Android API levels
ANDROID_API=28 ANDROID_API_32BIT=24 ./build-libsodium.sh android

# Custom iOS minimum version
IOS_VERSION_MIN=13.0 ./build-libsodium.sh ios

# Custom macOS minimum version
MACOS_VERSION_MIN=10.15 ./build-libsodium.sh macos

CI/CD Usage

# Non-interactive mode (skip confirmations)
./build-libsodium.sh all --yes

# Clean build from scratch
./build-libsodium.sh clean --yes
./build-libsodium.sh macos --version 1.0.18 --yes

Output Structure

dist/
├── include/                          # Common headers (all platforms)
│   └── sodium/
│       ├── core.h
│       ├── crypto_box.h
│       └── ...
│
├── macos/
│   └── lib/
│       ├── libsodium.a              # Universal (x86_64 + arm64)
│       └── pkgconfig/
│           └── libsodium.pc
│
├── linux/
│   └── lib/
│       ├── libsodium.a              # Linux (native arch)
│       └── pkgconfig/
│           └── libsodium.pc
│
├── wasm/
│   └── lib/
│       ├── libsodium.a              # WebAssembly
│       └── pkgconfig/
│           └── libsodium.pc
│
├── windows/
│   └── lib/
│       ├── libsodium.a              # Windows x86_64
│       └── pkgconfig/
│           └── libsodium.pc
│
├── android/                          # Android (all ABIs)
│   ├── armv7/lib/libsodium.a        # ARMv7 (armeabi-v7a)
│   ├── arm64/lib/libsodium.a        # ARM64 (arm64-v8a)
│   ├── x86/lib/libsodium.a          # x86 (32-bit)
│   └── x86_64/lib/libsodium.a       # x86_64 (64-bit)
│
├── ios/                              # iOS
│   ├── arm64/lib/libsodium.a        # Device (arm64)
│   └── simulator/lib/libsodium.a    # Simulator (x86_64 + arm64)
│
├── Libsodium.xcframework/            # iOS XCFramework
│   ├── ios-arm64/
│   └── ios-arm64_x86_64-simulator/
│
├── Libsodium.xcframework.zip         # For Swift Package Manager
│
├── VERSION.txt                       # Built version info
├── SHA256SUMS.txt                    # Checksums
├── SETUP_ENV.sh                      # Environment setup helper
│
└── libsodium-*.tar.gz               # Distribution packages
    ├── libsodium-1.0.18-macos.tar.gz
    ├── libsodium-1.0.18-linux.tar.gz
    ├── libsodium-1.0.18-android.tar.gz
    └── ...

Using Built Libraries

pkg-config (Recommended)

# Source the environment setup script
source dist/SETUP_ENV.sh

# Now you can use pkg-config
pkg-config --cflags libsodium
# Output: -I/path/to/dist/include

pkg-config --libs libsodium
# Output: -L/path/to/dist/macos/lib -lsodium

CMake

# CMakeLists.txt

# Option 1: Using pkg-config
find_package(PkgConfig REQUIRED)
pkg_check_modules(LIBSODIUM REQUIRED libsodium)

target_include_directories(your_target PRIVATE ${LIBSODIUM_INCLUDE_DIRS})
target_link_libraries(your_target PRIVATE ${LIBSODIUM_LIBRARIES})

# Option 2: Manual linking
add_library(sodium STATIC IMPORTED)
set_target_properties(sodium PROPERTIES
    IMPORTED_LOCATION "${CMAKE_SOURCE_DIR}/dist/macos/lib/libsodium.a"
)
target_include_directories(your_target PRIVATE "${CMAKE_SOURCE_DIR}/dist/include")
target_link_libraries(your_target PRIVATE sodium)

Makefile

LIBSODIUM_DIR = dist

CFLAGS += -I$(LIBSODIUM_DIR)/include
LDFLAGS += -L$(LIBSODIUM_DIR)/macos/lib -lsodium

your_program: your_program.c
	$(CC) $(CFLAGS) $< -o $@ $(LDFLAGS)

Xcode (iOS)

Drag dist/Libsodium.xcframework into your Xcode project
In General → Frameworks, Libraries, and Embedded Content
Set Embed to "Do Not Embed" (static framework)

Android NDK

# Android CMakeLists.txt

add_library(sodium STATIC IMPORTED)
set_target_properties(sodium PROPERTIES
    IMPORTED_LOCATION "${CMAKE_SOURCE_DIR}/../dist/android/${ANDROID_ABI}/lib/libsodium.a"
)

target_include_directories(your_app PRIVATE "${CMAKE_SOURCE_DIR}/../dist/include")
target_link_libraries(your_app PRIVATE sodium)

Emscripten (WebAssembly)

emcc your_program.c \
  -I dist/include \
  dist/wasm/lib/libsodium.a \
  -o your_program.js

Verification

Verify Checksums

# View all checksums
cat dist/SHA256SUMS.txt

# Verify a specific library
shasum -a 256 dist/macos/lib/libsodium.a
# Compare with SHA256SUMS.txt

Verify Universal Binaries

# macOS universal binary
lipo -info dist/macos/lib/libsodium.a
# Output: Architectures in the fat file: libsodium.a are: x86_64 arm64

# iOS simulator
lipo -info dist/ios/simulator/lib/libsodium.a
# Output: Architectures in the fat file: libsodium.a are: x86_64 arm64

Check Library Contents

# List symbols
nm dist/linux/lib/libsodium.a | grep crypto_box

# Check file type
file dist/android/arm64/lib/libsodium.a

# Check library size
ls -lh dist/*/lib/libsodium.a

Test Library

# Simple test program
cat > test.c << 'EOF'
#include <sodium.h>
#include <stdio.h>

int main(void) {
    if (sodium_init() < 0) {
        return 1;
    }
    printf("libsodium %s\n", sodium_version_string());
    return 0;
}
EOF

# Compile and run
gcc test.c -I dist/include -L dist/linux/lib -lsodium -o test
./test
# Output: libsodium 1.0.18

Environment Variables

Variable	Description	Default
`ANDROID_NDK_HOME`	Path to Android NDK root	-
`NDK_ROOT`	Alternative to `ANDROID_NDK_HOME`	-
`ANDROID_API`	Android API level for 64-bit ABIs	`21`
`ANDROID_API_32BIT`	Android API level for 32-bit ABIs	`19`
`MACOS_VERSION_MIN`	Minimum macOS deployment target	`11.0`
`IOS_VERSION_MIN`	Minimum iOS deployment target	`11.0`
`JOBS`	Number of parallel make jobs	Auto-detected
`DEBUG`	Enable verbose build output (`0` or `1`)	`0`
`DIST_DIR`	Custom output directory	`./dist`
`EXTRA_CFLAGS`	Additional C compiler flags	-
`EXTRA_LDFLAGS`	Additional linker flags	-

Troubleshooting

Build fails with "configure: error: ..."

Solution: Install missing build dependencies

# macOS
brew install autoconf automake libtool

# Linux
sudo apt-get install autoconf automake libtool build-essential

Android: "Toolchain not found"

Solution: Verify NDK installation and environment variable

# Check NDK path
echo $ANDROID_NDK_HOME
ls -la $ANDROID_NDK_HOME/toolchains/llvm/prebuilt/

# Common issue: Wrong NDK version (need r21+)
$ANDROID_NDK_HOME/ndk-build --version

iOS: "xcodebuild: error: SDK ... cannot be located"

Solution: Install/update Xcode Command Line Tools

# Remove old tools
sudo rm -rf /Library/Developer/CommandLineTools

# Reinstall
xcode-select --install

# Verify
xcrun --show-sdk-path

WebAssembly: "emcc: command not found"

Solution: Activate Emscripten SDK

# Navigate to emsdk directory
cd /path/to/emsdk

# Activate for current shell
source ./emsdk_env.sh

# Verify
which emcc
emcc --version

macOS: "lipo: can't create universal file"

Solution: Build both architectures first

# Clean and rebuild
./build-libsodium.sh clean --yes
./build-libsodium.sh macos

Low disk space warning

The script checks for at least 500MB free space. To skip:

./build-libsodium.sh macos --yes

Permission denied errors

# Make script executable
chmod +x build-libsodium.sh

# Or run with bash
bash build-libsodium.sh macos

FAQ

Can I build for Windows on Windows?

This script uses MinGW for cross-compilation from Linux/macOS. For native Windows builds, consider:

Official libsodium Windows builds
Building with CMake and MSVC
Using WSL2 and running this script

How do I build a specific version?

# Use any git tag
./build-libsodium.sh macos --version 1.0.18

# Or branch
./build-libsodium.sh macos --version stable

# Or commit hash
./build-libsodium.sh macos --version a1b2c3d4

Can I use this in CI/CD?

Yes! Use the --yes flag to skip confirmations:

./build-libsodium.sh all --yes --version 1.0.18

See .github/workflows directory for GitHub Actions examples.

Does this work on Apple Silicon (M1/M2)?

Yes! The script auto-detects and builds universal binaries for macOS. It also supports building on ARM64 Linux hosts for Android cross-compilation.

How do I speed up builds?

Install ccache (automatically detected):

brew install ccache  # macOS
sudo apt-get install ccache  # Linux

Increase parallel jobs:
```
./build-libsodium.sh all --jobs 16
```

Are the built libraries optimized?

Yes! All builds use -O3 optimization and platform-specific flags. Tests are also run on native builds to ensure correctness.

Can I redistribute the built libraries?

Yes, libsodium is licensed under the ISC license, which allows redistribution. Just include the libsodium license file. This build script itself is MIT licensed.

Contributing

Contributions are welcome! Here's how you can help:

Report bugs - Open an issue with details
Suggest features - Propose enhancements
Submit PRs - Fix bugs or add features
Improve docs - Fix typos, add examples
Test - Try on different platforms

Development

# Fork and clone
git clone https://github.com/toprakdeviren/libsodium-builder.git
cd libsodium-builder

# Make changes to build-libsodium.sh

# Test your changes
./build-libsodium.sh linux

# Enable debug mode for verbose output
DEBUG=1 ./build-libsodium.sh macos

Code Style

Use shellcheck for linting
Follow existing code style
Add comments for complex logic
Update README if adding features

License

This project is licensed under the MIT License - see the LICENSE file for details.

Third-Party Licenses

libsodium - ISC License

Author

Uğur Toprakdeviren

GitHub: @toprakdeviren
Email: [email protected]

Acknowledgments

Frank Denis and contributors for libsodium
The open-source community for cross-compilation tools and examples
All contributors to this project

Related Projects

libsodium - Official libsodium repository
libsodium.js - JavaScript/WebAssembly port
swift-sodium - Swift wrapper

If this project helped you, please consider giving it a star!

Made with ❤️ by the community

Report Bug · Request Feature

Name		Name	Last commit message	Last commit date
Latest commit History 3 Commits
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
build-libsodium.sh		build-libsodium.sh

License

toprakdeviren/libsodium-builder

Folders and files

Latest commit

History

Repository files navigation

libsodium-builder

Table of Contents

Why This Script?

Features

Supported Platforms

Quick Start

Prerequisites

Required for All Builds

macOS

Linux (Debian/Ubuntu)

Linux (RHEL/CentOS/Fedora)

Platform-Specific Requirements

Installation

Option 1: Clone Repository

Option 2: Direct Download

Option 3: Add to PATH

Usage

Interactive Mode

Command Line Mode

Commands

Options

Examples

Basic Usage

Version Control

Performance Tuning

Custom Configuration

CI/CD Usage

Output Structure

Using Built Libraries

pkg-config (Recommended)

CMake

Makefile

Xcode (iOS)

Android NDK

Emscripten (WebAssembly)

Verification

Verify Checksums

Verify Universal Binaries

Check Library Contents

Test Library

Environment Variables

Troubleshooting

Build fails with "configure: error: ..."

Android: "Toolchain not found"

iOS: "xcodebuild: error: SDK ... cannot be located"

WebAssembly: "emcc: command not found"

macOS: "lipo: can't create universal file"

Low disk space warning

Permission denied errors

FAQ

Contributing

Development

Code Style

License

Third-Party Licenses

Author

Acknowledgments

Related Projects

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages