diff --git a/docs/document/Nix/docs/1. The Nix Language/Language Features/With-Expression.md b/docs/document/Nix/docs/1. The Nix Language/Language Features/With-Expression.md index af3e8ea7..86a293c4 100644 --- a/docs/document/Nix/docs/1. The Nix Language/Language Features/With-Expression.md +++ b/docs/document/Nix/docs/1. The Nix Language/Language Features/With-Expression.md @@ -35,5 +35,19 @@ When another module is imported, all attributes will be deconstructed from the s ```nix let foo = null; in - with (import ./foo.nix) + with (import ./foo.nix); +``` + +## Practical usage + +```nix +{ config, pkgs, ... }: + +{ + home.packages = with pkgs; [ + git + ripgrep + neovim + ]; +} ``` diff --git a/docs/document/Nix/docs/2. Nix Cli Families/nix-channel.md b/docs/document/Nix/docs/2. Nix Cli Families/nix-channel.md deleted file mode 100644 index 2a039216..00000000 --- a/docs/document/Nix/docs/2. Nix Cli Families/nix-channel.md +++ /dev/null @@ -1,31 +0,0 @@ -# nix-channel - -## Add channel - -```bash -nix-channel --add [] -``` - -:::info -`channel_alias` is optional, defaults to `nixpkgs` -::: - -## List channel - -```bash -nix-channel --list -``` - -## Remove channel - -```bash -nix-channel --remove -``` - -## Update channel - -You'll need to fetch channel info after adding new channels - -```bash -nix-channel --update [<...channel_alias>] # update all or specific channels -``` diff --git a/docs/document/Nix/docs/Home Manager/2. Installation.md b/docs/document/Nix/docs/Home Manager/1. Installation.md similarity index 51% rename from docs/document/Nix/docs/Home Manager/2. Installation.md rename to docs/document/Nix/docs/Home Manager/1. Installation.md index cf2f66a8..b7377d0e 100644 --- a/docs/document/Nix/docs/Home Manager/2. Installation.md +++ b/docs/document/Nix/docs/Home Manager/1. Installation.md @@ -1,6 +1,6 @@ -# Initialize home-manager +# Installation -## Pre-enable flake(Optional) +## Enable flake(optional) It's recommended to use home-manager together with flake enabled. If you haven't enabled flake yet, do the following for single user: @@ -15,6 +15,9 @@ or the following for multi-users: sudo sh -c 'echo "experimental-features = nix-command flakes" >> /etc/nix/nix.conf' ``` +> [!NOTE] +> This documentation only uses home-manager with flakes. + ## Installation ### Add channel for home-manager @@ -31,6 +34,9 @@ nix-channel --add https://github.com/nix-community/home-manager/archive/master.t nix-channel --add https://github.com/nix-community/home-manager/archive/release-24.05.tar.gz home-manager && nix-channel --update ``` +> [!TIP] +> For version number, see: [Nix Channels](https://channels.nixos.org/) + ### Install ```bash @@ -38,7 +44,7 @@ nix-shell '' -A install ``` :::info -`` is the channel alias you in previous step. Replace it by yours if necessary. +`` is the channel alias you set in previous step. Replace it with yours if necessary. ::: After this command, `home-manager` should be available. @@ -52,36 +58,30 @@ home-manager init ``` This command generates `flake.nix`, `home.nix` under `~/.config/home-manager/` +- `flake.nix`: metadata used for home-manager. +- `home.nix`: entry point of home-manager. Uses attribute set from `flake.nix`. -## Enable flake using home-manager +## Apply home-manager profile -After setting up home-manager, we can manage nix with it, we don't need to sepcifiy any config in `nix.conf` any more! -Home-manager will handle things for us. -So add the following to function body in `home.nix` to enable flakes instead of what we just do earlier in `nix.conf`. +By default, `home-manager init{:sh}` generates by current username. ```nix -nix = { - # ... - settings.experimental-features = ["nix-command" "flakes"]; -}; +# generated in home.nix +home.username = "sharpchen"; ``` -## Apply config +So it should be valid to switch to the profile with following: -If you're ready to restore config specified in `home.nix` to your machine - -```bash -home-manager switch +```sh +home-manager switch --flake ~/.config/home-manager#$USER ``` -This command uses `home.nix` and `flake.nix` under `~/.config/home-manager/` by default. +This is how you restore a home-manager profile for a user. +And this also implies home-manager can handle multiple users' profiles. -If you feel uncertain, try - -```bash -home-manager build -``` +> [!TIP] +> Set an command alias for `home-manager switch`! -This generates a folder named `result/` under `~/.config/home-manager/` +## Reference -Currently we just tested the minimal config generated by home-manager, next we'll learn everything home-manager can do. +- [Home Manager Manual](https://nix-community.github.io/home-manager/index.xhtml#sec-install-standalone) diff --git a/docs/document/Nix/docs/Home Manager/1. What's home-manager.md b/docs/document/Nix/docs/Home Manager/1. What's home-manager.md deleted file mode 100644 index 0c4fad31..00000000 --- a/docs/document/Nix/docs/Home Manager/1. What's home-manager.md +++ /dev/null @@ -1,9 +0,0 @@ -# What's home-manager? - -home-manager is global config manager used for setting up environment with reproducibility in UNIX systems. -What it can setup includes: - -- Environment variables in your shell session -- Custom commands in your shell session -- Packages in your system -- Dotfiles diff --git a/docs/document/Nix/docs/Home Manager/2. Install Packages.md b/docs/document/Nix/docs/Home Manager/2. Install Packages.md new file mode 100644 index 00000000..834be791 --- /dev/null +++ b/docs/document/Nix/docs/Home Manager/2. Install Packages.md @@ -0,0 +1,86 @@ +# Install Packages + +There's two ways to install packages using home-manager. + +- `home.packages`: for any package exists in a channel. +- `programs.`: for build in options for certain package by home-manager. + +## Install from a channel + +`home.packages` provides a explicit way to include what package should be installed. +`pkgs` here is a channel unpacked from the`flake.nix`. + +```nix +{ config, pkgs, ... }: { + home.packages = with pkgs; [ + git # package names came from channel + neovim + ripgrep + openssh + lazygit + ]; +} +``` + +```nix +{ + description = "Home Manager configuration of sharpchen"; + + inputs = { + # Specify the source of Home Manager and Nixpkgs. + unstablePkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable"; + stablePkgs.url = "github:nixos/nixpkgs/nixos-24.05"; + home-manager = { + url = "github:nix-community/home-manager"; + inputs.nixpkgs.follows = "unstablePkgs"; + }; + }; + + outputs = { stablePkgs, unstablePkgs, home-manager, ... }: + let + system = "x86_64-linux"; + pkgs = unstablePkgs.legacyPackages.${system}; + stable = unstablePkgs.legacyPackages.${system}; + in { + homeConfigurations."sharpchen" = home-manager.lib.homeManagerConfiguration { + inherit pkgs; # [!code highlight] + # Specify your home configuration modules here, for example, + # the path to your home.nix. + modules = [ + ./home.nix + ]; + + # Optionally use extraSpecialArgs + # to pass through arguments to home.nix + extraSpecialArgs = { inherit stable; }; + }; + }; +} +``` + +> [!TIP] +> How do I know the package name? +> Search on [NixOS Search](https://search.nixos.org/packages) to find the package you want. + +## Install by builtin option + +For some packages, home-manager provides builtin options to set them up. +It seems `pkgs` is not involved, actually it was used by default for `programs.`. +So we should always make sure `pkgs` exists as a parameter for the function in `home.nix`, should be discussed later. + +```nix +{ config, pkgs, ... }: { + programs.git = { + enable = true; + userName = "foo"; + userEmail = "example@bar.com"; + }; +} +``` + +*`enable` implies that the package will be installed implicitly.* + +:::info +Only few packages has builtin options, how do I know what attribute I can set? +Check out [Home-manager Options](https://nix-community.github.io/home-manager/options.xhtml) and search `programs.` +::: diff --git a/docs/document/Nix/docs/Home Manager/3. Managing Dotfiles.md b/docs/document/Nix/docs/Home Manager/3. Managing Dotfiles.md new file mode 100644 index 00000000..69172f9b --- /dev/null +++ b/docs/document/Nix/docs/Home Manager/3. Managing Dotfiles.md @@ -0,0 +1,16 @@ +# Managing Dotfiles + +Managing config files is what a traiditional pm can't do. +Home manager provides some approaches to do it. + +- `home.file`: directly creates a file with content to a path. + - `text`: use string to represent content right inside nix file. + - `source`: specifiy a target path to a file as the source of config. +- `xdg.configFile`: use xdg config path as base path. +- symlink + +## `home.file` + +## `xdg.configFile` + +## diff --git a/docs/document/Nix/docs/Home Manager/Add Packages.md b/docs/document/Nix/docs/Home Manager/Add Packages.md deleted file mode 100644 index e15e42e6..00000000 --- a/docs/document/Nix/docs/Home Manager/Add Packages.md +++ /dev/null @@ -1,58 +0,0 @@ -# Add Packages and Manage Config File - -There's two ways to install packages using home-manager. - -- `home.packages` -- `programs.` - -## Install only - -`home.packages` provides a explicit way to include what package should be installed. - -```nix -{ config, pkgs, ... }: { - home.packages = with pkgs; [ - git - neovim - ripgrep - openssh - lazygit - ]; -} -``` - -**However, you won't be able to config the package in a same place.** -To generate any file as well as config file, use `home.file.""` - -```nix -{ cofig, pkgs, ... }: { - home.file.".gitconfig" = { - text = '' - [user] - name = "foo" - email = "example@bar.com" - '' - }; -} -``` - -## Install and config by builtin option - -**For some packages, nix provides builtin options to set them up programmatically** - -```nix -{ cofig, pkgs, ... }: { - programs.git = { - enable = true; - userName = "foo"; - userEmail = "example@bar.com"; - }; -} -``` - -*`enable` implies that the package will be installed implicitly.* - -:::info -Only few packages has builtin options, how do I know? -Go to [Home-manager Options](https://nix-community.github.io/home-manager/options.xhtml) and search `programs.` -::: diff --git a/docs/document/Nix/docs/Home Manager/Multiple Channels with Flakes.md b/docs/document/Nix/docs/Home Manager/Multiple Channels with Flakes.md new file mode 100644 index 00000000..dcc535f8 --- /dev/null +++ b/docs/document/Nix/docs/Home Manager/Multiple Channels with Flakes.md @@ -0,0 +1,61 @@ +# Multiple Channels with Flakes + +You might want to use stable and unstable at the same time. +As mentioned earlier, all attributes are passed from `flake.nix` to `home.nix`. +So adding a new channel is simply adding a new attribute in `flake.nix` and use it in `home.nix`. + +## Choose one as your default channel + +You should already know that `pkgs` is a essential attribute that we should always assign. +`programs.` uses `pkgs` attribute implicitly, it's like a default channel solution. +So just pick one channel as you like for it. A lot nix users actually prefer unstable over stable because it's not that unstale. + +```nix +{ + description = "Home Manager configuration of sharpchen"; + + inputs = { + # Specify the source of Home Manager and Nixpkgs. + # Names can be any + unstablePkgs.url = "github:nixos/nixpkgs/nixpkgs-unstable"; # [!code highlight] + stablePkgs.url = "github:nixos/nixpkgs/nixos-24.05"; # [!code highlight] + home-manager = { + url = "github:nix-community/home-manager"; + inputs.nixpkgs.follows = "unstablePkgs"; + }; + }; + + outputs = { stablePkgs, unstablePkgs, home-manager, ... }: + let + system = "x86_64-linux"; + pkgs = unstablePkgs.legacyPackages.${system}; # choose unstable as pkgs # [!code highlight] + stable = unstablePkgs.legacyPackages.${system}; # name non-default channel as you like! # [!code highlight] + in { + homeConfigurations."sharpchen" = home-manager.lib.homeManagerConfiguration { + inherit pkgs; # export `pkgs` here, this is the only one `pkgs` # [!code highlight] + # Specify your home configuration modules here, for example, + # the path to your home.nix. + modules = [ + ./home.nix + ]; + + # Optionally use extraSpecialArgs + # to pass through arguments to home.nix + extraSpecialArgs = { inherit stable; }; # export `stable` as arg here # [!code highlight] + }; + }; +} +``` + +Then add the attribute name in the funtion of `home.nix`: + +```nix +{ config, pkgs, stable, ... }: # add `stable` here # [!code highlight] +{ + # ... + home.packages = [ + stable.harper # [!code highlight] + stable.tmux # [!code highlight] + ]; +} +```