I recently learned about nixpkgs-lint, so I'm pushing I force-pushed a few changes (squashed from a WIP branch) to make this package nixpkgs-lint-compliant 😉.

I just added separate commits, which I can squash once the review is positive 😉. I'm trying to test this against the real hardware but am having issues with the udev rules. When one installs this package they get to add a udev.packages statement to their nixos-configuration in order to honor the udev rules for this package, however; since I'm building this package through nix-build I'm not sure how to get the udev rules applied to my system. Currently, the app is unable to see the device until I do and I want to perform a thorough test on my own machine so I'll have to test connecting to the device as well.

My first approach was to checkout this branch and attempt to nix-rebuild test against this branch. That way I can add udev.packages to my nixos-configuration and perhaps even add the package in my configuration for installation. The only problem with this is that my machine resorts to pulling all those builds from a month ago (I've upgraded and garbage collected since), which I can't sit through at the moment.

Another approach would be to rebase this entire branch on top of my current nixos-version --revision and then add the udev.packages rule to my configuration and nixos-rebuild-ing it against the rebased branch.

@infinisil how would you go about this? Thanks for the assistance on this 🙇

Rebasing is perfectly fine.

As for the udev rules, you can create a NixOS module which when enabled adds the rules. You can also have the NixOS module install the package (see nixos/modules/programs/java.nix for an example). That way the user can just do something like programs.digitalbitbox.enabled = true; to install the package and set up the necessary udev rules. Of course, this means the package may have limited, if any, use outside of NixOS.

Also another nitpick, I've listed the package under the all-packages attribute digitalbitbox but the name is dbb-app-${version}. I'm pretty sure I should be consistent. Now dbb-app is the repository name that I'm pulling this package from, but digitalbitbox is more meaningful at first glance. Shall I just rename all dbb-app names to digitalbitbox?

@emmanuelrosa thanks for the tip. I'll be working on the module next 😉 was looking at the nitrokey, which is relatively similar to what you explained. They added their module in nixos/modules/hardware/nitrokey.nix so I'll basically learn from that and provide a software-only package, but also a hardware module.

As for my other problem. I basically rebased all my work and then cherry-picked it on top of nixos-version --revision in order to apply the udev changes and list this package in my configuration. Just got into the digitalbitbox so it all works 😄... at least on my machine 😨

So here's the current status.

The easiest way to install the Digitalbitbox application is by adding

{
  programs.digitalbitbox.enable = true;
}

to your nixos-configuration which will install the digitalbitbox package and apply the udev rules by enabling the digitalbitbox hardware module.

That programs.digitalbitbox.enable = true line is basically equivalent to:

{
  environment.systemPackages = [ pkgs.digitalbitbox ];
  hardware.digitalbitbox.enable = true;
}

The hardware module for digitalbitbox simply allows the udev rules by means of

{
  services.udev.packages = [ pkgs.digitalbitbox ];
}

This is looking great 👍

What plan do you have to guide users toward the proper installation procedure? A user may simply try adding digitalbitbox to environment.systemPackages or using nix-env to install it.

Hey @emmanuelrosa, I don't really have a good plan there. I was thinking about:

1. providing some usage instructions in the package's expression -- which I just did with this diff
2. issuing a PR to the NixOS documentation to make a mention of Digital Bitbox and the install procedure
3. issuing a request for change to the Digital Bitbox Linux installation page in order to add NixOS-specific instructions
4. embedding a notification or warning on an attempt to just install the software package (I'm clueless as to how I would go about this)
5. writing a blog post about it (but discoverability on this option is low, hence it is the last resort)

I think option 1 suffices for now, wouldn't you agree? I don't see a good place where I could make a note of this in the NixOS docs and the Digital Bitbox linux installation page is relatively distro agnostic. Not sure they want to start venturing down that road where they'll have to keep and maintain installation instructions for different distros.

Which options do you have mind that I haven't listed yet?

Option 1 is very good. The NixOS documentation has a section containing application-specific instructions. Here's an example of one that's short and sweet: https://nixos.org/nixos/manual/index.html#sec-hidepid

Packages can optionally have a long description in the meta set, so that's another option. The long description is visible at https://nixos.org/nixos/packages.html, but I'm not sure if nix-env displays it.

You're right, discover-ability is tough at this point. Hopefully between the code comments, docs, and perhaps also a mention in the package's description, users will find what they need.

Okay... I've added the longDescription as proposed by @emmanuelrosa. That sounded like a good idea. 👍

About the manual... the example you gave pertains to a rather general security feature. Structure-wise, I don't think that it would make sense for every maintainer to add information on the usage details for their packages to the manual. I foresee this document becoming a cloud of noise in which it becomes even harder to find things.

Perhaps, I misunderstood you in which case I hope you'll help me clarify what you meant.

Yeah, that was a bad example on my part. A better one is the Emacs chapter.

My reasoning behind suggesting that you add instructions to the NixOS documentation is that your package requires an abnormal install process. You're right, the documentation should not contain usage details for every package. But documentation is ideal for installs that require something other than the common environment.systemPackages or nix-env due to the current discover-ability limitations. An experienced NixOS user will probably check the Nix expression and see your comments, and intermediate user may see the long description, but new users don't know to look in those places.

My goal is to make the NixOS learning curve shallower (that sounds awful, I know) to encourage more talent to saddle up and become contributors, just like you and I.

Thanks for the pull request. Looked pretty good!

@Mic92 thanks for reviewing. This PR has been straddling along for quite a while, after the multiple review session it's at least good to know the outcome was relatively decent acceptable or decent 😄.