mirror of
https://github.com/foo-dogsquared/nixos-config.git
synced 2025-01-31 04:58:01 +00:00
bahaghari: update README
This commit is contained in:
parent
203eda736a
commit
88dde1b679
@ -1,31 +1,127 @@
|
||||
= Bahaghari
|
||||
:toc:
|
||||
|
||||
:fn-container-comment: footnote:[IDK why would someone do this with Bahaghari but whatever, your system, your rules.]
|
||||
:fn-specialization-comment: footnote:[Which I can see is useful for separating rices and booting into them separately for whatever reason (again, your system, your rules but my guess is because you're a control freak).]
|
||||
|
||||
Bahaghari (Tagalog word for "rainbow") is a specialized set of Nix modules for generating and applying themes.
|
||||
|
||||
Bahaghari (Tagalog word for "rainbow" or a "king's loincloth" if you prefer) is a specialized set of Nix modules for generating and applying themes.
|
||||
Mainly useful for making your ricing process with NixOS and home-manager environments easier.
|
||||
This module set should allow for some flexibility for your use case.
|
||||
|
||||
At its current state, Bahaghari is considered unstable and might have breaking changes more than what you'd expect.
|
||||
|
||||
|
||||
|
||||
|
||||
[#getting-started]
|
||||
== Getting started
|
||||
|
||||
To get started using Bahaghari, you have to set some things up first.
|
||||
The way how Bahaghari expects you to use it is by choosing one (or more if you want) of the module sets which you can view more details at <<module-sets, its dedicated section>>.
|
||||
For now, let's assume that you are using Tinted Theming module set in your NixOS configuration which you can set it up with the following code.
|
||||
|
||||
// TODO: Change all of the URLs once this moves into its own repo.
|
||||
First, you'll have to install Bahaghari as part of your Nix project or whatever.
|
||||
There are multiple ways to do this.
|
||||
|
||||
* We'll first start with the increasingly popular method of including Nix dependencies with https://zero-to-nix.com/concepts/flakes[Nix flakes], a built-in way of pinning them dependencies.
|
||||
+
|
||||
[source, nix]
|
||||
----
|
||||
{
|
||||
inputs.bahaghari.url = "github:foo-dogsquared/nixos-config?dir=subprojects/bahaghari";
|
||||
|
||||
# ...
|
||||
|
||||
outputs = { nixpkgs, ... }@inputs: {
|
||||
nixosConfigurations = nixpkgs.lib.nixosSystem {
|
||||
modules = [
|
||||
inputs.bahaghari.nixosModules.bahaghari
|
||||
];
|
||||
};
|
||||
};
|
||||
}
|
||||
----
|
||||
|
||||
* You can also import the dependencies with a pinning tool (that is not flakes) like https://github.com/nmattia/niv[niv].
|
||||
+
|
||||
[source, shell]
|
||||
----
|
||||
# I would recommend to rename this into more specific package name.
|
||||
niv add foo-dogsquared/nixos-config --name foo-dogsquared-nixos-config
|
||||
----
|
||||
+
|
||||
Then somewhere in your Nix code, you can add it like in the following listing.
|
||||
+
|
||||
[source, nix]
|
||||
----
|
||||
let
|
||||
sources = import ./nix/sources.nix;
|
||||
bahaghari = import "${sources.foo-dogsquared-nixos-config}/subprojects/bahaghari" { };
|
||||
in
|
||||
{
|
||||
imports = [ bahaghari.nixosModules.bahaghari ];
|
||||
}
|
||||
----
|
||||
|
||||
* Lastly, you can import it through https://zero-to-nix.com/concepts/channels[channels].
|
||||
+
|
||||
[source, shell]
|
||||
----
|
||||
# You'll likely to run this as root since you'll be dealing with your NixOS
|
||||
# system after all.
|
||||
nix-channel --add "https://github.com/foo-dogsquared/nixos-config/archive/master.tar.gz" foo-dogsquared-nixos-config
|
||||
----
|
||||
+
|
||||
Similarly to importing it through niv, you can now use it somewhere in your Nix code.
|
||||
+
|
||||
[source, nix]
|
||||
----
|
||||
{ config, lib, ... }:
|
||||
|
||||
let
|
||||
bahaghari = import <foo-dogsquared-nixos-config/subprojects/bahaghari> { };
|
||||
in
|
||||
{
|
||||
imports = [ bahaghari.nixosModules.bahaghari ];
|
||||
}
|
||||
----
|
||||
|
||||
Importing the module will also import Bahaghari's library set (`bahaghariLib`), making it available as `bahaghariLib` module argument.
|
||||
|
||||
If for whatever reason you need Bahaghari library outside of using it with Bahaghari, you can also import it yourself.
|
||||
Here's one way to set it to be available in the module of your environment.
|
||||
|
||||
[source, nix]
|
||||
----
|
||||
{ pkgs, ... }:
|
||||
|
||||
let
|
||||
# This is assuming you have Bahaghari as part of NIX_PATH.
|
||||
bahaghari = import <foo-dogsquared-nixos-config/subprojects/bahaghari> { };
|
||||
in
|
||||
{
|
||||
_module.args.bahaghariLib =
|
||||
import bahaghari.bahaghariLib { inherit pkgs };
|
||||
}
|
||||
----
|
||||
|
||||
|
||||
|
||||
|
||||
[#module-sets]
|
||||
== Module sets
|
||||
|
||||
As a whole, Bahaghari is more like a set of sets, a metaset, if you will.
|
||||
Specifically, it is composed of module sets of which has different ways to use them.
|
||||
Here is the exhaustive list of them and its details.
|
||||
|
||||
|
||||
[#tinted-theming]
|
||||
=== Tinted Theming
|
||||
|
||||
Bahaghari has a module set for interacting with Tinted Theming standard schemes and templates.
|
||||
To use it, simply import it and you're pretty much set.
|
||||
|
||||
// TODO: Nix code importing here
|
||||
|
||||
Optionally, you can also import Bahaghari's library set for Tinted Theming.
|
||||
Like most of the library components from Bahaghari, it requires both the `pkgs` and `lib` attribute found from the standard nixpkgs module system.
|
||||
|
||||
// TODO: Nix code importing BahagharLib for TT. Also code samples for it.
|
||||
|
||||
This module is designed to closely follow Tinted Theming's standard while offering some convenience with the library set.
|
||||
For example, you can use `importYAML` from Bahaghari's standard library set to easily import standard Base16 schemes into Nix-representable data which you can press onto your Nix configuration.
|
||||
@ -33,6 +129,7 @@ For example, you can use `importYAML` from Bahaghari's standard library set to e
|
||||
// TODO: GNOME HIG module set
|
||||
// TODO: Material You module set
|
||||
|
||||
[#templated-configuration-sub-modules]
|
||||
=== Templated configuration sub-modules
|
||||
|
||||
Bahaghari offers a pre-configured version of already existing modules for NixOS, home-manager, and NixVim quite similar to Stylix's `stylix.targets.<name>` submodules.
|
||||
@ -41,20 +138,90 @@ To make use of this, you'll have to import Bahaghari module set's
|
||||
// TODO: Pictures and sample configurations
|
||||
|
||||
|
||||
[#comparison-with-other-modules]
|
||||
== Comparison with other modules
|
||||
|
||||
[#nix-colors]
|
||||
=== nix-colors
|
||||
|
||||
Bahaghari initially started as a derivative to nix-colors as a single Nix module entirely dedicated for Tinted Theming standard.
|
||||
It was created to address its limitation of allowing only one colorscheme at a time which limits a lot of possible applications.
|
||||
Most notably, the feature I'm looking for is generating multiple colorscheme templates for different applications which is nice for hybrid deployments of home-manager-plus-mutable-configurations (AKA traditional dotfiles).
|
||||
Most notably, the feature I'm looking for is generating multiple colorscheme templates for different applications which is nice for hybrid deployments of home-manager-plus-mutable-configurations (AKA traditional dotfiles) and for mixed installations of NixOS and home-manager (or whatever else that can be combined).
|
||||
|
||||
While Bahaghari eventually diverged from nix-colors entirely, it can be used as an alternative specifically with Bahaghari's Tinted Theming module set.
|
||||
You can replicate nix-colors' preference of allowing a default set of colorscheme
|
||||
You can replicate nix-colors' preference of allowing a default set of colorscheme by creating a module argument holding the name of the preferred colorscheme.
|
||||
Here's one way to implement it.
|
||||
|
||||
== Stylix
|
||||
[source, nix]
|
||||
----
|
||||
{ bahaghariLib, ... }:
|
||||
|
||||
While Bahaghari can be used similarly to Stylix, it isn't completely 1-to-1 to Stylix as it focuses on the holistic side of customization including for fonts and wallpaper.
|
||||
On the other hand, Bahaghari completely focuses on colorscheme generation. footnote:[While Bahaghari as a project can also focus beyond colorschemes similar to Stylix, it isn't a part of the vision for now. Who knows, it might be. ;)]
|
||||
{
|
||||
bahaghari.tinted-theming.schemes.bark-on-a-tree =
|
||||
bahaghariLib.importYAML ./base16-bark-on-a-tree.yml;
|
||||
|
||||
Bahaghari also took some cues from Stylix specifically from its Stylix targets which became the pre-templated configurations submodules for each of the module set.
|
||||
# Just assume there's importing more schemes here.
|
||||
|
||||
_module.args.defaultTintedThemingScheme = "bark-on-a-tree";
|
||||
}
|
||||
----
|
||||
|
||||
|
||||
|
||||
|
||||
[#stylix]
|
||||
=== Stylix
|
||||
|
||||
While Bahaghari can be used similarly to Stylix, it isn't completely 1-to-1 to Stylix as the latter focuses on the holistic side of customization including for fonts and wallpaper.
|
||||
On the other hand, Bahaghari completely focuses on colorscheme generation. footnote:[While Bahaghari as a project can also focus beyond colorschemes similar to Stylix, it isn't a part of the vision for now.]
|
||||
|
||||
Bahaghari also took some cues from Stylix specifically from its Stylix targets which became the pre-templated configurations submodules for each of the design system module set (e.g., Tinted Theming).
|
||||
|
||||
|
||||
|
||||
|
||||
[#hacking-this-project]
|
||||
== Hacking this project
|
||||
|
||||
If you want to hack this hack, you can do so with Nix.
|
||||
This is mostly a Nix project so you only need Nix and you're good to go.
|
||||
|
||||
The folder structure of this project should be intuitive but we'll give a recap like a good manager.
|
||||
Here's the rundown.
|
||||
|
||||
* link:./default.nix[./default.nix] is basically the entrypoint for our user and onlookers who're looking to extend Bahaghari.
|
||||
This is used both by the flake- and non-flake-based setups for consistency (and also easier to maintain).
|
||||
|
||||
* link:./lib/[./lib/] is where the Bahaghari library set lives.
|
||||
It takes a lot of cues from nixpkgs how the library is maintained with individual files separated by purpose and the module sets (most of the time).
|
||||
|
||||
* link:./modules/[./modules/] is where the Bahaghari module sets reside.
|
||||
All of them are then separated by... module sets and are organized by the aforementioned `default.nix`.
|
||||
|
||||
* link:./tests/[./tests/] is where the test suites reside.
|
||||
We'll cover how to interact with the test suite right after this section.
|
||||
|
||||
|
||||
[#testing]
|
||||
=== Testing
|
||||
|
||||
This project comes with a test suite for... testing things.
|
||||
You know, for the purpose of preventing as much regression and catching as many potential bugs before releasing this for the users.
|
||||
|
||||
For the Bahaghari library set, we have a testing infrastructure set all set in link:./tests/[`./tests/`].
|
||||
This relies on the `lib.debug.runTests` from nixpkgs which is enough for our simple needs of making sure the functions are correct.
|
||||
To run the test suite, here's one way to do it.footnote:test-setup-assumption[Assuming you have the new Nix CLI and have nixpkgs as part of `NIX_PATH`.]
|
||||
|
||||
[source, shell]
|
||||
----
|
||||
nix eval -f ./tests lib
|
||||
----
|
||||
|
||||
We also have a test suites for the Nix module sets.
|
||||
Similarly from the library set testing, it relies on nixpkgs' NixOS test integration.footnote:[For now, we only test these with NixOS since most of Bahaghari is environment-agnostic anyways. We're more concerned if it can used as intended.]
|
||||
You can test those puppies out with the following command.footnote:test-setup-assumption[]
|
||||
|
||||
[source, shell]
|
||||
----
|
||||
nix eval -f ./tests modules
|
||||
----
|
||||
|
||||
Loading…
Reference in New Issue
Block a user