Zig 0.15.2 Development Environment (CentOS Stream 9) AMI Administrator Guide

1. Quick Start Information

Install Information:

OS: CentOS Stream 9
Zig version: 0.15.2 (Latest Stable)
ZLS version: 0.15.1 (Zig Language Server)
Zig Install Directory: /usr/local/zig/
ZLS Install Directory: /usr/local/bin/

Connection Methods:

Access the instance via SSH using the ec2-user user.
Use sudo to run commands requiring root privileges.

Verify Installation:

Check Zig version: zig version
Check ZLS version: zls --version

Firewall Configuration:

Please allow SSH port 22.
For security, it is recommended to limit SSH access to trusted IPs only.

2. Overview

Welcome to the Easycloud Zig Development Environment AMI. This image is based on CentOS Stream 9 and provides a complete, production-ready Zig development stack.

Core Features of this AMI:

Latest Stable Stack: Integrates Zig 0.15.2 (latest stable release), avoiding outdated repository versions.
IDE Ready: Pre-installed ZLS 0.15.1 provides out-of-the-box code completion and jump-to-definition for VS Code Remote and Neovim.
Drop-in C/C++ Compiler: Environment is configured to use zig cc and zig c++ as direct replacements for GCC/Clang for cross-compilation.
Clean & Standard: Installed in /usr/local directory following Linux FHS standards, without polluting system libraries.

Target Scenarios:

Zig language development and learning
Systems programming with modern tooling
Cross-compilation projects (replacing GCC/Clang with Zig)
IDE-assisted development with VS Code Remote or Neovim

3. First Launch & Access

Step 1: Configure Security Group (Cloud Firewall)

In your cloud provider's console (e.g., AWS EC2), add inbound rules to the security group for this instance to allow:

TCP Port 22 (SSH): Required for server access (Mandatory).

Security Recommendation:

Restrict SSH access to your office IP address or VPN subnet only.
Avoid opening SSH to 0.0.0.0/0 (the entire internet) in production environments.

Step 2: Connect via SSH

Get your instance's public IP address from the cloud console.
Use your SSH client to connect:
```
ssh ec2-user@[Your_Public_IP]
```
If prompted about host authenticity, type yes to continue.

Step 3: Verify Installation

After logging in, run the following commands to verify the development environment is ready:

Check Zig Compiler:

zig version

Expected output: 0.15.2

Check ZLS Language Server:

zls --version

Expected output: 0.15.1

Check Installation Paths:

which zig
which zls

Expected output:

/usr/bin/zig
/usr/local/bin/zls

4. AMI Detailed Configuration & Architecture

This AMI has been configured with a complete Zig development stack. All installations follow Linux FHS (Filesystem Hierarchy Standard) conventions.

Installation Architecture:

/usr/local/zig/           <- Zig compiler and standard library
    ├── zig               <- Main compiler binary (200MB+)
    ├── lib/std/          <- Standard library source code
    └── doc/              <- Official documentation

/usr/bin/zig              <- Symlink to /usr/local/zig/zig (global command)

/usr/local/bin/zls        <- ZLS language server binary (standalone)

4.1. Zig Compiler Installation

Paths

Path	Type	Description
`/usr/local/zig/`	Directory	Core asset library containing all Zig runtime files
`/usr/local/zig/zig`	File	The actual Zig compiler binary (200MB+)
`/usr/local/zig/lib/std/`	Directory	Zig standard library source code (used for IDE jump-to-definition)
`/usr/local/zig/doc/`	Directory	Official documentation and license files
`/usr/bin/zig`	Symlink	Points to `/usr/local/zig/zig`, enables global `zig` command

Configuration (How-To-Create)

The following steps were performed to install Zig 0.15.2:

# 1. Install prerequisites
sudo dnf update -y
sudo dnf install -y wget tar xz git gcc which

# 2. Download official binary package (0.15.2)
wget https://ziglang.org/download/0.15.2/zig-linux-x86_64-0.15.2.tar.xz

# 3. Extract to /usr/local
# Parameters: x(extract), v(verbose), J(xz format), f(file)
sudo tar xvJf zig-linux-x86_64-0.15.2.tar.xz -C /usr/local/

# 4. Rename directory (standardize path)
# Rename the long versioned folder to a clean 'zig' name
cd /usr/local/
sudo mv zig-linux-x86_64-0.15.2/ zig

# 5. Create global symlink
# Establish /usr/bin/zig -> /usr/local/zig/zig connection
# This allows all users to run 'zig' without PATH configuration
sudo ln -sf /usr/local/zig/zig /usr/bin/zig

# 6. Verify installation
zig version
# Expected output: 0.15.2

Why This Configuration

Binary Distribution: Using official pre-compiled binaries ensures optimal performance and compatibility, avoiding compilation issues on the target system.
Symlink Strategy: Creating a symlink in /usr/bin/ ensures the zig command is available system-wide without modifying any user's PATH environment variable.
Standard Location: /usr/local/ is the standard location for locally installed software, keeping system directories clean.

4.2. ZLS Language Server Installation

Path

/usr/local/bin/zls

Configuration (How-To-Create)

The following steps were performed to install ZLS 0.15.1:

# 1. Return to user home directory
cd ~

# 2. Download ZLS 0.15.1 (must match Zig 0.15.x series)
wget https://github.com/zigtools/zls/releases/download/0.15.1/zls-x86_64-linux.tar.xz

# 3. Prepare temporary extraction directory
# The ZLS archive has no root folder, so files would scatter if extracted directly
mkdir zls_temp
tar xvJf zls-x86_64-linux.tar.xz -C zls_temp

# 4. Deploy to /usr/local/bin
# Move binary to system-level binary directory
sudo mv zls_temp/zls /usr/local/bin/zls

# 5. Grant execution permission
sudo chmod +x /usr/local/bin/zls

# 6. Clean up temporary files
rm -rf zls_temp zls-x86_64-linux.tar.xz

# 7. Verify installation
zls --version
# Expected output: 0.15.1

Why ZLS 0.15.1

Version Compatibility: ZLS versions must match the major.minor version of Zig. ZLS 0.15.1 is the compatible release for Zig 0.15.x series.
IDE Integration: ZLS provides Language Server Protocol (LSP) support, enabling features like code completion, diagnostics, and jump-to-definition in editors like VS Code and Neovim.
Standard Path: /usr/local/bin/ is automatically included in PATH on most systems, allowing VS Code plugins to auto-detect ZLS.

5. Verification & Testing

5.1. Basic Version Check

# Check Zig compiler version
zig version
# Expected output: 0.15.2

# Check ZLS language server version
zls --version
# Expected output: 0.15.1

5.2. Zig Compilation Test (Hello World)

This is the core functionality test, verifying Zig can correctly compile native code:

# 1. Create a simple Zig program
echo 'const std = @import("std");
pub fn main() !void {
    std.debug.print("Hello, Zig 0.15.2 on CentOS!\n", .{});
}' > hello.zig

# 2. Compile it (generate executable)
zig build-exe hello.zig

# 3. Run it
./hello
# Expected output: Hello, Zig 0.15.2 on CentOS!

# 4. Clean up
rm -f hello hello.zig hello.o
rm -rf zig-cache

5.3. Zig CC Test (C/C++ Cross-Compilation)

This is a key feature. Verify that Zig can compile C code like GCC:

# 1. Create a simple C program
echo '#include <stdio.h>
int main() {
    printf("Zig CC is acting like GCC!\n");
    return 0;
}' > test.c

# 2. Compile with zig cc (acting as gcc)
zig cc test.c -o test_binary

# 3. Run it
./test_binary
# Expected output: Zig CC is acting like GCC!

# 4. Verify version masquerading (optional)
zig cc --version
# Expected output: clang version 19.x.x ... (shows LLVM/Clang backend)

# 5. Clean up
rm -f test.c test_binary

5.4. ZLS Path Verification (IDE Ready)

Verify the language server is in the standard location for IDE auto-detection:

# Check command location
which zls
# Expected output: /usr/local/bin/zls

# Check execution permission
ls -l $(which zls)
# Expected output: -rwxr-xr-x ... (must have x permission)

6. Service Management (Quick Reference)

Zig is a compiler, not a service, so there are no systemd services to manage. Here are the key commands:

Zig Compiler Commands:

Compile Zig source: zig build-exe <file.zig>
Run Zig code directly: zig run <file.zig>
Build project: zig build
Format code: zig fmt <file.zig>

Zig as C/C++ Compiler:

Compile C code: zig cc <file.c> -o <output>
Compile C++ code: zig c++ <file.cpp> -o <output>

ZLS Commands:

Check version: zls --version
ZLS runs automatically when invoked by an IDE/editor

7. Important File Locations

File Path	Purpose
`/usr/local/zig/`	Zig compiler installation directory (core assets)
`/usr/local/zig/zig`	Zig compiler binary
`/usr/local/zig/lib/std/`	Zig standard library source code
`/usr/local/zig/doc/`	Official documentation
`/usr/bin/zig`	Global symlink to Zig compiler
`/usr/local/bin/zls`	ZLS language server binary

8. Troubleshooting

Problem: `zig` command not found

Symptom: Running zig version returns "command not found".

Possible Causes:

Symlink Missing: The symlink may not have been created correctly.
```
ls -l /usr/bin/zig
```
Solution: Recreate the symlink:
```
sudo ln -sf /usr/local/zig/zig /usr/bin/zig
```
Installation Directory Missing:
```
ls -l /usr/local/zig/
```
Solution: If the directory doesn't exist, the installation may have failed. Re-download and extract the Zig package.

Problem: `zls` command not found

Symptom: Running zls --version returns "command not found".

Solution: Verify ZLS is installed and has correct permissions:

ls -l /usr/local/bin/zls

If missing, reinstall ZLS following Section 4.2.

Problem: ZLS not detected by VS Code

Symptom: VS Code Zig extension shows "ZLS not found".

Possible Causes:

Path Issue: VS Code may not see /usr/local/bin in its PATH. Solution: In VS Code settings, manually set the ZLS path:
```
"zig.zls.path": "/usr/local/bin/zls"
```

Permission Issue:

ls -l /usr/local/bin/zls

Solution: Ensure execute permission:

sudo chmod +x /usr/local/bin/zls

Problem: Zig compilation fails with "GLIBC not found"

Symptom: Error message mentioning GLIBC version incompatibility.

Cause: This typically occurs when running binaries compiled on a newer system.

Solution: Zig includes its own libc. Use the following flag to use Zig's bundled musl libc:

zig build-exe -target x86_64-linux-musl hello.zig

Problem: Version mismatch between Zig and ZLS

Symptom: ZLS shows errors about incompatible Zig version.

Cause: ZLS major.minor version must match Zig's major.minor version.

Solution: This AMI ships with Zig 0.15.2 and ZLS 0.15.1, which are compatible. If you upgrade Zig, you must also upgrade ZLS to a matching version.

9. Advanced Topics

9.1. Using Zig as a C/C++ Compiler

One of Zig's most powerful features is its ability to act as a drop-in replacement for GCC or Clang. This is especially useful for:

Cross-compilation: Zig can easily target other architectures and operating systems.
Hermetic builds: Zig bundles its own libc, ensuring reproducible builds.
Faster linking: Zig's linker is often faster than traditional linkers.

Example: Cross-compile C code for ARM:

echo '#include <stdio.h>
int main() { printf("Hello ARM!\n"); return 0; }' > test.c

# Cross-compile for ARM Linux
zig cc -target aarch64-linux-gnu test.c -o test_arm

# Check the binary type
file test_arm
# Output: test_arm: ELF 64-bit LSB executable, ARM aarch64...

9.2. IDE Configuration

VS Code Setup:

Install the "Zig Language" extension (zigtools.zig)
The extension should auto-detect ZLS at /usr/local/bin/zls

If not, manually configure in settings:

{
  "zig.path": "/usr/bin/zig",
  "zig.zls.path": "/usr/local/bin/zls"
}

Neovim Setup (with nvim-lspconfig):

require('lspconfig').zls.setup{
  cmd = { '/usr/local/bin/zls' },
}

9.3. Upgrading Zig

To upgrade to a newer Zig version:

# 1. Download new version
wget https://ziglang.org/download/X.Y.Z/zig-linux-x86_64-X.Y.Z.tar.xz

# 2. Remove old installation
sudo rm -rf /usr/local/zig

# 3. Extract new version
sudo tar xvJf zig-linux-x86_64-X.Y.Z.tar.xz -C /usr/local/
cd /usr/local/
sudo mv zig-linux-x86_64-X.Y.Z/ zig

# 4. Symlink remains valid (points to /usr/local/zig/zig)

# 5. Verify
zig version

Important: After upgrading Zig, also upgrade ZLS to a compatible version.

10. Final Notes

This AMI provides a complete, production-ready Zig development environment with the following key benefits:

Key Takeaways:

Latest stable Zig 0.15.2 compiler with full standard library
Pre-configured ZLS 0.15.1 for IDE integration
Drop-in C/C++ compiler capability via zig cc and zig c++
Clean installation following Linux FHS standards

For support or questions, please contact the Easycloud team.

1. Quick Start Information​

2. Overview​

3. First Launch & Access​

Step 1: Configure Security Group (Cloud Firewall)​

Step 2: Connect via SSH​

Step 3: Verify Installation​

4. AMI Detailed Configuration & Architecture​

4.1. Zig Compiler Installation​

Paths​

Configuration (How-To-Create)​

Why This Configuration​

4.2. ZLS Language Server Installation​

Path​

Configuration (How-To-Create)​

Why ZLS 0.15.1​

5. Verification & Testing​

5.1. Basic Version Check​

5.2. Zig Compilation Test (Hello World)​

5.3. Zig CC Test (C/C++ Cross-Compilation)​

5.4. ZLS Path Verification (IDE Ready)​

6. Service Management (Quick Reference)​

7. Important File Locations​

8. Troubleshooting​

Problem: zig command not found​

Problem: zls command not found​

Problem: ZLS not detected by VS Code​

Problem: Zig compilation fails with "GLIBC not found"​

Problem: Version mismatch between Zig and ZLS​

9. Advanced Topics​

9.1. Using Zig as a C/C++ Compiler​

9.2. IDE Configuration​

9.3. Upgrading Zig​

10. Final Notes​

1. Quick Start Information

2. Overview

3. First Launch & Access

Step 1: Configure Security Group (Cloud Firewall)

Step 2: Connect via SSH

Step 3: Verify Installation

4. AMI Detailed Configuration & Architecture

4.1. Zig Compiler Installation

Paths

Configuration (How-To-Create)

Why This Configuration

4.2. ZLS Language Server Installation

Path

Configuration (How-To-Create)

Why ZLS 0.15.1

5. Verification & Testing

5.1. Basic Version Check

5.2. Zig Compilation Test (Hello World)

5.3. Zig CC Test (C/C++ Cross-Compilation)

5.4. ZLS Path Verification (IDE Ready)

6. Service Management (Quick Reference)

7. Important File Locations

8. Troubleshooting

Problem: `zig` command not found

Problem: `zls` command not found

Problem: ZLS not detected by VS Code

Problem: Zig compilation fails with "GLIBC not found"

Problem: Version mismatch between Zig and ZLS

9. Advanced Topics

9.1. Using Zig as a C/C++ Compiler

9.2. IDE Configuration

9.3. Upgrading Zig

10. Final Notes