Skip to content

NIX.md

Latest commit

 

History

History
630 lines (448 loc) · 10.5 KB

NIX.md

File metadata and controls

630 lines (448 loc) · 10.5 KB

Nix

This repository provides a Nix flake for developing, building, running, and installing Bottles Next.

The flake currently supports x86_64-linux.

Bottles Next uses Git submodules for its Cargo workspace crates. The flake enables automatic submodule handling through:

inputs.self.submodules = true;

A recent Nix version is therefore required. Nix 2.27 or newer is recommended.

Local development

Clone the repository:

git clone https://github.com/bottlesdevs/bottles-next.git
cd bottles-next

Initialize all Git submodules:

git submodule update --init --recursive

Alternatively, clone the repository and its submodules in one command:

git clone --recurse-submodules \
  https://github.com/bottlesdevs/bottles-next.git

cd bottles-next

Verify the submodules:

git submodule status

A line beginning with - means that the corresponding submodule has not been initialized.

Development shell

Enter the development shell:

nix develop

The development shell includes:

  • Rust and Cargo
  • rust-analyzer
  • rustfmt and Clippy
  • protobuf and gRPC tools
  • pkg-config
  • CMake and Make
  • OpenSSL
  • the MinGW cross compiler
  • the x86_64-pc-windows-gnu Rust target

The development shell supports building both the native Linux components and the Windows Wine bridge.

Building

Build the complete project as a Nix package:

nix build

The default package contains:

bin/bottles-cli
bin/bottles-server
libexec/bottles-next/bottles-winebridge.exe

The build output is available through the result symlink:

ls -R result

Build the package explicitly by name:

nix build .#bottles-next

Show the complete build log:

nix build --print-build-logs

Running

Run the default application:

nix run

The default application is bottles-cli.

Run the CLI explicitly:

nix run .#bottles-cli

Run the server:

nix run .#bottles-server

Pass arguments after --:

nix run .#bottles-cli -- --help
nix run .#bottles-server -- --help

Checking the flake

Build and validate all checks exposed by the flake:

nix flake check

Show complete build logs:

nix flake check --print-build-logs

The checks verify that:

  • the complete package builds;
  • bottles-cli is installed;
  • bottles-server is installed;
  • bottles-winebridge.exe is installed;
  • the installed files use the expected paths.

Formatting

Format the Nix files:

nix fmt

Building directly from the remote repository

The repository uses Git submodules.

For reliable remote builds, use the generic Git fetcher and enable submodules explicitly:

nix build \
  'git+https://github.com/bottlesdevs/bottles-next.git?submodules=1'

Do not use the shorter github: reference for remote builds. Depending on the installed Nix version, the GitHub-specific fetcher may return the parent repository without the contents of its submodules.

Development shell from the remote repository

nix develop \
  'git+https://github.com/bottlesdevs/bottles-next.git?submodules=1'

Run the default application from the remote repository

nix run \
  'git+https://github.com/bottlesdevs/bottles-next.git?submodules=1'

Run the CLI explicitly

nix run \
  'git+https://github.com/bottlesdevs/bottles-next.git?submodules=1#bottles-cli'

Run the server

nix run \
  'git+https://github.com/bottlesdevs/bottles-next.git?submodules=1#bottles-server'

Arguments can be passed after --:

nix run \
  'git+https://github.com/bottlesdevs/bottles-next.git?submodules=1#bottles-cli' \
  -- --help

Building a specific branch or revision

Build a specific branch:

nix build \
  'git+https://github.com/bottlesdevs/bottles-next.git?ref=main&submodules=1'

Build a fork:

nix build \
  'git+https://github.com/hotplugindev/bottles-next.git?ref=branch-name&submodules=1'

Build an exact commit:

nix build \
  'git+https://github.com/bottlesdevs/bottles-next.git?rev=COMMIT_HASH&submodules=1'

Using an exact commit gives the most predictable remote build.

Using the flake in NixOS or Home Manager

Add Bottles Next as an explicit Git input with submodules enabled:

{
  inputs = {
    bottles-next = {
      type = "git";
      url = "https://github.com/bottlesdevs/bottles-next.git";
      submodules = true;
    };
  };
}

It is recommended to make Bottles Next use the same Nixpkgs input as the consuming configuration:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";

    bottles-next = {
      type = "git";
      url = "https://github.com/bottlesdevs/bottles-next.git";
      submodules = true;

      inputs.nixpkgs.follows = "nixpkgs";
    };
  };
}

When testing a fork or branch:

{
  inputs = {
    bottles-next = {
      type = "git";
      url = "https://github.com/hotplugindev/bottles-next.git";
      ref = "branch-name";
      submodules = true;

      inputs.nixpkgs.follows = "nixpkgs";
    };
  };
}

After adding or changing the input, update the lock file:

nix flake update bottles-next

On older Nix versions:

nix flake lock --update-input bottles-next

Home Manager

Install the package directly from the flake:

{ inputs, pkgs, ... }:

{
  home.packages = [
    inputs.bottles-next.packages.${pkgs.stdenv.hostPlatform.system}.default
  ];
}

Because Bottles Next currently supports only x86_64-linux, it can also be referenced explicitly:

{ inputs, ... }:

{
  home.packages = [
    inputs.bottles-next.packages.x86_64-linux.default
  ];
}

NixOS

Install the package system-wide:

{ inputs, pkgs, ... }:

{
  environment.systemPackages = [
    inputs.bottles-next.packages.${pkgs.stdenv.hostPlatform.system}.default
  ];
}

It can also be referenced explicitly:

{ inputs, ... }:

{
  environment.systemPackages = [
    inputs.bottles-next.packages.x86_64-linux.default
  ];
}

Rebuild the system:

sudo nixos-rebuild switch --flake .#your-hostname

For example:

sudo nixos-rebuild switch --flake ~/nixos#pc

Using the overlay

The flake exposes a default Nixpkgs overlay.

Add it to the consuming configuration:

{ inputs, ... }:

{
  nixpkgs.overlays = [
    inputs.bottles-next.overlays.default
  ];
}

Bottles Next can then be installed through pkgs:

{ pkgs, ... }:

{
  environment.systemPackages = [
    pkgs.bottles-next
  ];
}

The same works with Home Manager:

{ pkgs, ... }:

{
  home.packages = [
    pkgs.bottles-next
  ];
}

Use either the package output directly or the overlay. Using both is unnecessary.

Complete NixOS example

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";

    bottles-next = {
      type = "git";
      url = "https://github.com/bottlesdevs/bottles-next.git";
      submodules = true;

      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs =
    {
      self,
      nixpkgs,
      bottles-next,
      ...
    }:
    {
      nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";

        modules = [
          {
            environment.systemPackages = [
              bottles-next.packages.x86_64-linux.default
            ];
          }
        ];
      };
    };
}

Complete NixOS example using the overlay

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-26.05";

    bottles-next = {
      type = "git";
      url = "https://github.com/bottlesdevs/bottles-next.git";
      submodules = true;

      inputs.nixpkgs.follows = "nixpkgs";
    };
  };

  outputs =
    {
      self,
      nixpkgs,
      bottles-next,
      ...
    }:
    {
      nixosConfigurations.my-host = nixpkgs.lib.nixosSystem {
        system = "x86_64-linux";

        modules = [
          (
            { pkgs, ... }:
            {
              nixpkgs.overlays = [
                bottles-next.overlays.default
              ];

              environment.systemPackages = [
                pkgs.bottles-next
              ];
            }
          )
        ];
      };
    };
}

Updating dependencies

Update all flake inputs:

nix flake update

Update only Nixpkgs:

nix flake update nixpkgs

Update only the Rust overlay:

nix flake update rust-overlay

After updating inputs, verify the project:

nix flake check --print-build-logs
nix build --print-build-logs

Review and commit changes to flake.lock together with the corresponding project changes.

Dirty Git tree warnings

Nix may show:

warning: Git tree is dirty

This means that the repository contains uncommitted changes.

It does not normally prevent the flake from building.

Inspect the changes with:

git status

Commit or discard the changes before publishing a release so that the release refers to a clean repository state.

Troubleshooting submodules

Local build reports a missing workspace crate

For example:

failed to read crates/download-manager/Cargo.toml
No such file or directory

Initialize all submodules:

git submodule update --init --recursive

Verify them:

git submodule status

Then retry:

nix build

Remote build reports a missing workspace crate

Use the generic Git fetcher rather than the github: shorthand:

nix build \
  'git+https://github.com/bottlesdevs/bottles-next.git?submodules=1'

For a NixOS or Home Manager input, use:

bottles-next = {
  type = "git";
  url = "https://github.com/bottlesdevs/bottles-next.git";
  submodules = true;
};

Nix rejects inputs.self.submodules

The flake requires a recent Nix version for automatic local submodule handling.

Check the installed version:

nix --version

Nix 2.27 or newer is recommended.

On NixOS, a recent Nix package can be selected with:

nix.package = pkgs.nixVersions.latest;

Rebuild the system and verify the version before using the flake.

A submodule uses an SSH URL

Remote Nix builds should not depend on SSH authentication.

All public submodules should use HTTPS URLs in .gitmodules, for example:

[submodule "crates/download-manager"]
    path = crates/download-manager
    url = https://github.com/bottlesdevs/download-manager.git

After changing a submodule URL:

git submodule sync --recursive
git submodule update --init --recursive