Flux on Linux - Setup Guide

This guide walks you through setting up a clean, effective Flux development environment on Linux. We'll use standard tools that integrate well with the Unix philosophy: Sublime Text for editing, your terminal for compilation, and LLVM from your package manager.

Toolchain Overview

Flux on Linux requires:

Python 3.8+ - Runs the Flux compiler
LLVM/Clang - Compiles LLVM IR to native code and handles linking
llvmlite - Python bindings to LLVM for code generation
Git - To clone the Flux repository
Sublime Text - Your code editor (optional but recommended)

Quick Start

For the impatient, here's the complete setup:

# Install toolchain
sudo apt update
sudo apt install python3 python3-pip llvm clang git

# Install Python dependencies
pip3 install llvmlite==0.41.0 dataclasses

# Clone Flux
git clone https://github.com/kvthweatt/FluxLang.git
cd FluxLang

# Test compilation
python3 fxc.py tests/test.fx --log-level 3

# Install Sublime Text (optional)
wget -qO - https://download.sublimetext.com/sublimehq-pub.gpg | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/sublimehq-archive.gpg
echo "deb https://download.sublimetext.com/ apt/stable/" | sudo tee /etc/apt/sources.list.d/sublime-text.list
sudo apt update
sudo apt install sublime-text

Done! Skip to Verification Steps to confirm everything works.

Detailed Installation

System Packages

Ubuntu/Debian:

sudo apt update
sudo apt install python3 python3-pip llvm clang git

Fedora/RHEL:

sudo dnf install python3 python3-pip llvm clang git

Arch Linux:

sudo pacman -S python python-pip llvm clang git

Python Dependencies

Install llvmlite and dataclasses:

pip3 install llvmlite==0.41.0 dataclasses

Note: If you encounter permissions issues, either:

Use --user flag: pip3 install --user llvmlite==0.41.0
Or use a virtual environment (see Advanced Configuration)

Sublime Text

Ubuntu/Debian:

wget -qO - https://download.sublimetext.com/sublimehq-pub.gpg | gpg --dearmor | sudo tee /etc/apt/trusted.gpg.d/sublimehq-archive.gpg
echo "deb https://download.sublimetext.com/ apt/stable/" | sudo tee /etc/apt/sources.list.d/sublime-text.list
sudo apt update
sudo apt install sublime-text

Fedora:

sudo rpm -v --import https://download.sublimetext.com/sublimehq-rpm-pub.gpg
sudo dnf config-manager --add-repo https://download.sublimetext.com/rpm/stable/x86_64/sublime-text.repo
sudo dnf install sublime-text

Arch Linux:

# Sublime Text is in AUR
yay -S sublime-text-4
# or
paru -S sublime-text-4

Alternative editors: Any text editor works fine - VS Code, Vim, Emacs, Kate, Gedit, nano. Sublime Text is just our recommendation for a clean, fast experience.

Clone Flux

git clone https://github.com/kvthweatt/FluxLang Flux
cd Flux

Verification Steps

1. Check Python

python3 --version                           # Should show 3.8+
python3 -c "import llvmlite; print('llvmlite OK')"

2. Check LLVM/Clang

clang --version                             # Should show LLVM version
llvm-config --version                       # Should match clang version

3. Check Git

git --version                               # Any recent version is fine

4. Test Flux Compilation

cd Flux
python3 fxc.py tests/test.fx --log-level 3

You should see compilation succeed and an executable created.

Development Workflow

Basic Compilation

Navigate to your Flux directory and compile a program:

cd ~/Flux
python3 fxc.py examples/hello.fx
./hello

Using Sublime Text

Open a Flux file:

subl examples/hello.fx

Open entire project:

subl ~/Flux

Build system (optional): Create a Flux build system in Sublime Text:

Tools → Build System → New Build System
Paste this configuration:

{
    "cmd": ["python3", "fxc.py", "$file"],
    "working_dir": "$folder",
    "selector": "source.flux",
    "file_regex": "^(.+?):(\\d+):(\\d+): (.*)$"
}

Save as Flux.sublime-build
Now you can press Ctrl+B to compile the current file

Syntax Highlighting (Optional)

Create a basic syntax file for Flux in Sublime Text:

Create ~/.config/sublime-text/Packages/User/Flux.sublime-syntax
Add basic syntax rules:

%YAML 1.2
---
name: Flux
file_extensions: [fx]
scope: source.flux

contexts:
  main:
    - match: '\b(def|object|struct|if|else|while|for|return|import|using|extern|compt|unsigned|data)\b'
      scope: keyword.control.flux
    
    - match: '\b(int|float|byte|bool|void|this)\b'
      scope: storage.type.flux
    
    - match: '//.*$'
      scope: comment.line.flux
    
    - match: '"'
      scope: punctuation.definition.string.begin.flux
      push: string
    
    - match: '\b\d+\b'
      scope: constant.numeric.flux

  string:
    - meta_scope: string.quoted.double.flux
    - match: '"'
      scope: punctuation.definition.string.end.flux
      pop: true

Restart Sublime Text, and .fx files will have basic highlighting.

Common Issues and Solutions

"Module 'llvmlite' not found"

Cause: llvmlite not installed or not in Python path.

Solutions:

# Try installing with --user
pip3 install --user llvmlite==0.41.0

# Or check if it's installed
pip3 list | grep llvmlite

# Ensure you're using the right Python
which python3

"Command 'clang' not found"

Cause: LLVM not installed.

Solutions:

# Reinstall LLVM
sudo apt install llvm clang

# Verify installation
which clang
clang --version

Permission Errors During Compilation

Causes: No write permissions in Flux directory, still compiling, executable open in debugger.

Solutions:

# Check permissions
ls -la

# Fix if needed
sudo chown -R $USER:$USER ~/FluxLang

Or just wait and try again.

Advanced Configuration

Virtual Environments

For isolated Python dependencies:

# Install venv if needed
sudo apt install python3-venv

# Create virtual environment
cd ~/FluxLang
python3 -m venv flux-env

# Activate it
source flux-env/bin/activate

# Install dependencies
pip install llvmlite==0.41.0 dataclasses

# Now compile normally
python fxc.py examples/hello.fx

# Deactivate when done
deactivate

Add to your ~/.bashrc for convenience:

alias flux-dev='cd ~/FluxLang && source flux-env/bin/activate'

Shell Aliases

Add these to ~/.bashrc or ~/.zshrc:

# Quick flux compilation
alias fluxc='python3 ~/FluxLang/fxc.py'

Apply changes:

source ~/.bashrc

Now you can:

fluxc myprogram.fx       # Compile

Build Directory

Flux creates temporary files in build/:

program.ll - LLVM IR code (human-readable)
program.o - Object file
program - Final executable (Linux)

Inspect generated IR:

python3 fxc.py program.fx
cat build/program.ll

Debugging Compilation

Enable detailed logging:

python3 fxc.py program.fx --log-level 4 --log-timestamp

This shows:

Lexing and parsing stages
LLVM IR generation
Clang invocation and arguments
Linking process

Understanding the Compilation Process

When you run python3 fxc.py program.fx, Flux:

Preprocesses - Handles macros, strips comments and empty lines, output to build\tmp.fx
Lexes - Breaks source code into tokens
Parses - Builds an Abstract Syntax Tree (AST)
Generates Code - Creates LLVM Intermediate Representation (IR)
Compiles - Uses Clang to convert IR to object code
Links - Creates final executable (Clang handles this on Linux)

Unlike Windows, Linux doesn't need a separate Visual Studio toolchain - Clang handles both compilation and linking using system libraries.

Next Steps

Now that your environment is ready:

Learn the language:
- Read docs/learn_flux_intro.md for a tutorial
- Study docs/lang_spec_reduced.md for core features
- Reference docs/lang_spec_full.md for complete details

Try examples:

cd examples
python3 ../fxc.py hello.fx && ./hello
python3 ../fxc.py bit_fields.fx && ./bit_fields

Write your first program:

subl myprogram.fx
# Write some Flux code
python3 fxc.py myprogram.fx
./myprogram

Explore the standard library:
```
ls src/stdlib/
```
Join the community:
- Discord - Ask questions, share projects
- GitHub - Report issues, contribute

This manual setup helps you:

Helps you understand how to compile Flux programs
Use familiar, standard Linux tools
Keep your development environment simple and transparent
Debug issues effectively when they arise

Linux's philosophy of small, composable tools aligns perfectly with Flux's design. You're using standard system packages, a straightforward Python script, and LLVM - the same toolchain that powers production languages.

As Flux matures toward self-hosting, we'll eventually provide a Flux-written installer - demonstrating the language's systems programming capabilities while maintaining this same transparency.

Happy Flux development!

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Flux on Linux - Setup Guide

Toolchain Overview

Quick Start

Detailed Installation

System Packages

Python Dependencies

Sublime Text

Clone Flux

Verification Steps

1. Check Python

2. Check LLVM/Clang

3. Check Git

4. Test Flux Compilation

Development Workflow

Basic Compilation

Using Sublime Text

Syntax Highlighting (Optional)

Common Issues and Solutions

"Module 'llvmlite' not found"

"Command 'clang' not found"

Permission Errors During Compilation

Advanced Configuration

Virtual Environments

Shell Aliases

Build Directory

Debugging Compilation

Understanding the Compilation Process

Next Steps

This manual setup helps you:

FilesExpand file tree

linux_setup_guide.md

Latest commit

History

linux_setup_guide.md

File metadata and controls

Flux on Linux - Setup Guide

Toolchain Overview

Quick Start

Detailed Installation

System Packages

Python Dependencies

Sublime Text

Clone Flux

Verification Steps

1. Check Python

2. Check LLVM/Clang

3. Check Git

4. Test Flux Compilation

Development Workflow

Basic Compilation

Using Sublime Text

Syntax Highlighting (Optional)

Common Issues and Solutions

"Module 'llvmlite' not found"

"Command 'clang' not found"

Permission Errors During Compilation

Advanced Configuration

Virtual Environments

Shell Aliases

Build Directory

Debugging Compilation

Understanding the Compilation Process

Next Steps

This manual setup helps you: