Nix flake for QB64 Phoenix Edition
Find a file
Repository files (latest commit first)
Filename Latest commit message Latest commit date
2026-10-01 21:51:51 -07:00
patches feat: enable system-wide installation and XDG compliance 2026-10-01 21:31:32 -07:00
.gitignore Initial commit 2026-06-17 05:16:31 +00:00
default.nix docs: add comprehensive usage guides for flake and non-flake users, add default.nix and overlay.nix 2026-10-01 21:51:51 -07:00
flake.lock Update flake.lock 2026-09-30 22:29:38 -07:00
flake.nix docs: add comprehensive usage guides for flake and non-flake users, add default.nix and overlay.nix 2026-10-01 21:51:51 -07:00
LICENSE relicense: replace AGPL-3.0 with MIT License for compatibility 2026-10-01 21:45:52 -07:00
overlay.nix docs: add comprehensive usage guides for flake and non-flake users, add default.nix and overlay.nix 2026-10-01 21:51:51 -07:00
package.nix feat: add debug build option and expose debug package targets in flake 2026-10-01 21:45:38 -07:00
README.md docs: add comprehensive usage guides for flake and non-flake users, add default.nix and overlay.nix 2026-10-01 21:51:51 -07:00

QB64-PE Nix Flake & Package

Nix packaging and flake for QB64 Phoenix Edition (QB64-PE), a modern extended BASIC compiler that retains QBasic/QB4.5 compatibility while compiling native C++ executables.

This package patches QB64-PE to function as a system-wide, read-only Nix package complying with standard Linux and XDG filesystem specifications:

  • User Configuration: $XDG_CONFIG_HOME/qb64pe (default ~/.config/qb64pe)
  • Help Database & Wiki Cache: $XDG_CACHE_HOME/qb64pe/help (default ~/.cache/qb64pe/help)
  • Transient Compiler State & Headers: $XDG_STATE_HOME/qb64pe (default ~/.local/state/qb64pe)
  • Working Directory: Preserves $CWD and does not force working directory changes on startup.
  • Runtime Toolchain: Automatically bundles and exposes g++, make, binutils, OpenGL, GLFW, ALSA, curl, and X11 headers/libraries to compiled programs.

Usage for Flake Users

1. Ad-Hoc CLI Usage

# Launch the IDE directly
nix run git+https://forge.kebado.net/barnett/qb64pe.git

# Launch the fast debug variant
nix run git+https://forge.kebado.net/barnett/qb64pe.git#debug

# Build the release package
nix build git+https://forge.kebado.net/barnett/qb64pe.git

# Build the fast debug variant (with unstripped gdb symbols)
nix build git+https://forge.kebado.net/barnett/qb64pe.git#default.debug

# Start an interactive shell with qb64pe in PATH
nix shell git+https://forge.kebado.net/barnett/qb64pe.git

2. NixOS or Home Manager (Flakes)

Add qb64pe to your flake inputs:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    qb64pe.url = "git+https://forge.kebado.net/barnett/qb64pe.git";
  };

  outputs = { self, nixpkgs, qb64pe, ... }: {
    nixosConfigurations.myhost = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        # Method 1: Add the package directly to systemPackages
        ({ pkgs, ... }: {
          environment.systemPackages = [
            qb64pe.packages.${pkgs.system}.default       # Release
            # qb64pe.packages.${pkgs.system}.default-dbg # Debug
          ];
        })

        # Method 2: Use the flake's default overlay
        ({ pkgs, ... }: {
          nixpkgs.overlays = [ qb64pe.overlays.default ];
          environment.systemPackages = [
            pkgs.qb64pe        # Release build
            # pkgs.qb64pe-debug # Debug build
          ];
        })
      ];
    };
  };
}

Usage for Non-Flake Users

1. Classic CLI Usage (nix-build, nix-shell, nix-env)

This repository includes a standard default.nix allowing direct use with traditional Nix commands:

# Build the release package
nix-build

# Build the debug package (-Og -g, unstripped symbols, ~1.5 min compile)
nix-build --arg debug true

# Enter a shell with qb64pe available in PATH
nix-shell -p '(import ./. {})'

# Install to user profile
nix-env -f . -iA default

2. Adding the Overlay to NixOS (configuration.nix)

You can import this repository's overlay.nix directly using builtins.fetchTarball in your /etc/nixos/configuration.nix:

{ pkgs, ... }:

let
  qb64peOverlay = import (builtins.fetchTarball {
    url = "https://forge.kebado.net/barnett/qb64pe/archive/main.tar.gz";
    # sha256 = "..."; # Optional: Pin NAR hash for reproducibility
  } + "/overlay.nix");
in
{
  nixpkgs.overlays = [ qb64peOverlay ];

  environment.systemPackages = with pkgs; [
    qb64pe        # Release build
    # qb64pe-debug # Debug build with gdb symbols
  ];
}

If you manage overlays via ~/.config/nixpkgs/overlays/, you can create a file ~/.config/nixpkgs/overlays/qb64pe.nix:

import (builtins.fetchTarball "https://forge.kebado.net/barnett/qb64pe/archive/main.tar.gz" + "/overlay.nix")

3. Incorporating package.nix in an Existing Custom Overlay

If you manage your own monolithic overlay or Nix monorepo, you can vendor or call package.nix directly:

Note

package.nix requires the patch directory ./patches/ relative to its location. Keep package.nix and patches/ together.

final: prev: {
  # Standard release package (-O2, stripped binary)
  qb64pe = (final.callPackage ./path/to/qb64pe/package.nix { }).overrideAttrs (old: {
    passthru = (old.passthru or { }) // {
      debug = final.qb64pe-debug;
    };
  });

  # Debug package (-Og -g, unstripped symbols, fast compile)
  qb64pe-debug = final.callPackage ./path/to/qb64pe/package.nix {
    debug = true;
  };
}

Build Targets & Debugging

Upstream QB64-PE compiles an internal 1.5-million-line monolithic C++ translation unit. This repository provides two configurations tailored for either production use or rapid development:

Package / Flake Attribute Build Type Flags & Settings Build Time Debugging (gdb)
pkgs.qb64pe
.#default
.#qb64pe
Release Default -O2, fortify hardening enabled, stripped binary ~11 min Basic stack
pkgs.qb64pe-debug
.#default.debug
.#qb64pe-debug
.#qb64pe-dbg
.#debug
Debug -Og -g -pipe -fno-var-tracking, fortify disabled, unstripped symbols ~1.5 min Full line info & symbols

Debugging with gdb

The debug build installs a symlink qb64pe-debug -> qb64pe and leaves symbols unstripped in libexec/qb64pe:

# Build the debug package
nix build .#default.debug   # (or nix-build --arg debug true)

# Run under GDB
gdb --args result/libexec/qb64pe

License

  • Nix Packaging & Flake: Licensed under the MIT License.
  • QB64 Phoenix Edition: Licensed under the MIT License, with third-party runtime components using various permissive and free licenses (Apache-2.0, BSD-3-Clause, curl, FTL, public domain, and zlib). See upstream licenses/README.md for full attribution.