Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

doc/haskell: begin bringing back haskell documentation to the nixpkgs manual #126674

Merged
merged 1 commit into from
Jan 14, 2023
Merged

doc/haskell: begin bringing back haskell documentation to the nixpkgs manual #126674

merged 1 commit into from
Jan 14, 2023

Conversation

sternenseemann
Copy link
Member

Motivation for this change

Reopened #126382 with a branch in NixOS/nixpkgs, so we can have PRs against this branch more easily.

@cdepillabout can you post our projected TOC in the comments here?

Things done
  • Tested using sandboxing (nix.useSandbox on NixOS, or option sandbox in nix.conf on non-NixOS linux)
  • Built on platform(s)
    • NixOS
    • macOS
    • other Linux distributions
  • Tested via one or more NixOS test(s) if existing and applicable for the change (look inside nixos/tests)
  • Tested compilation of all pkgs that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review wip"
  • Tested execution of all binary files (usually in ./result/bin/)
  • 21.11 Release Notes
    • (Package updates) Added a release notes entry if the change is major or breaking
    • (Module updates) Added a release notes entry if the change is significant
    • (Module addition) Added a release notes entry if adding a new NixOS module
  • Fits CONTRIBUTING.md.

@github-actions github-actions bot added 6.topic: haskell 8.has: documentation This PR adds or changes documentation labels Jun 12, 2021
@sternenseemann sternenseemann mentioned this pull request Jun 12, 2021
Closed
11 tasks
@ofborg ofborg bot added 10.rebuild-darwin: 0 This PR does not cause any packages to rebuild on Darwin 10.rebuild-linux: 0 This PR does not cause any packages to rebuild on Linux labels Jun 12, 2021
teto
teto reviewed Jun 12, 2021
View reviewed changes
doc/languages-frameworks/haskell.section.md Outdated
Haskell infrastructure in nixpkgs for development environments in
many cases. The main limitations are that we only provide first-class
support for the default compiler (currently GHC 8.10.4) and usually
only provide a default and (if different) the latest version of
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

latest being hackage (!= hackage) ?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

it's explained later on so I understand that if the package is on stackage, then the version is not necessarily the latest ?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah, I want to explain this in more detail in the section “Package Set Generation”. Basically we use the latest version of every package from hackage by default unless it is part of stackage or there has been a pin manually set up. In those cases we use the manual version constraint or the one from stackage to get the version of the standard attribute and additionally generate an attribute package-name_A_B_C_D which points to the latest version from hackage.

@teto
Copy link
Member

teto commented Jun 12, 2021

nice to have document this. I feel like this can be improved over time without necessarily having all in one PR.
Do you intend to mention haskell.nix ? since it helps wroking around nixpkgs limitations ?

@sternenseemann
Copy link
Member Author

nice to have document this. I feel like this can be improved over time without necessarily having all in one PR.
Do you intend to mention haskell.nix ? since it helps wroking around nixpkgs limitations ?

My current stance on this is that I'd like to accurately describe our infrastructure as well as its limitation, but I wouldn't like to link / endorse a third party project that is mostly run by a single company. Also this will probably just end with people coming to nixpkgs for their haskell.nix issues.

@cdepillabout
Copy link
Member

cdepillabout can you post our projected TOC in the comments here?

We had a video chat about what sections we want in our documentation.

So far, these sections have been completed in this PR:

  • overview and introduction
  • haskellPackages.mkDerivation (documented all arguments)

Here are the sections that are left to do, along with who volunteered to write them:

  • running cabal2nix and packaging your own packages (this is section in old manual as well?), callHackage (@maralorn)
  • section on overriding (@sternenseemann)
  • patch nix-doc to generate documentation from haskell.lib
  • document dev environment stuff shell.nix generation, env passthru, shellFor, developPackage
  • HLS (@maralorn)
  • contributing (@cdepillabout during zurihac?)
    • fixing a broken package
    • regenerate hackage2nix, as well as how the package set is generated in general
    • what do maintainers do
  • FAQs / How-To
  • reference
    • how does NIX_GHC work? (@maralorn)
    • IFD helpers (callCabal2nix, callHackage, callHackageDirect, etc)

Keep in mind that this is a very rough list, so there is likely to be big changes and reorganization.

Another important thing is that @maralorn suggested we follow the Divio documentation system: https://documentation.divio.com/

We should keep these four types of documentation in mind as we are writing this manual.

@sternenseemann
Copy link
Member Author

We should document the url capabilities of cabal2nix

@sternenseemann sternenseemann mentioned this pull request Jul 29, 2021
Open
@sternenseemann sternenseemann mentioned this pull request Sep 21, 2021
Closed
12 tasks
@sternenseemann sternenseemann force-pushed the haskell-nixpkgs-manual branch 2 times, most recently from 6bba508 to a6c22b8 Compare October 6, 2021 20:42
@sternenseemann
Copy link
Member Author

  • FAQ: Why don't build-tool-depends work with cabal v2 command?

@nixos-discourse
Copy link

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/why-are-these-derivations-so-different/18257/4

@sternenseemann
Copy link
Member Author

  • Why doesn't jailbreak-cabal lift version constraints in conditional blogs?

@sternenseemann
Copy link
Member Author

sternenseemann commented May 10, 2022 •
edited
Loading

Is this worth adding a comment to remind and explain [that buildTarget doesn't influence isExecutable …]?

maralorn
maralorn approved these changes Jul 18, 2022
View reviewed changes
Copy link
Member

@maralorn maralorn left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Absolutely great. Can‘t wait to see this merged so that we can all elaborate on it.

doc/languages-frameworks/haskell.section.md Outdated Show resolved Hide resolved
doc/languages-frameworks/haskell.section.md Outdated Show resolved Hide resolved
doc/languages-frameworks/haskell.section.md Show resolved Hide resolved
doc/languages-frameworks/haskell.section.md Show resolved Hide resolved
doc/languages-frameworks/haskell.section.md Outdated Show resolved Hide resolved
doc/languages-frameworks/haskell.section.md Show resolved Hide resolved
doc/languages-frameworks/haskell.section.md Outdated Show resolved Hide resolved
doc/languages-frameworks/haskell.section.md Show resolved Hide resolved
@sternenseemann
Copy link
Member Author

@cdepillabout
Copy link
Member

Request to document doJailbreak (and explain why we use the term "jailbreaking"): #35278

@cdepillabout cdepillabout mentioned this pull request Dec 22, 2022
Closed
@sternenseemann sternenseemann marked this pull request as ready for review January 14, 2023 11:41
@sternenseemann
doc/haskell: (re-)init haskell manual section
590f40b 
This restarts a Haskell section in the nixpkgs manual. The content
presented here has been written from scratch, although some parts of it
take inspiration from the existing haskell4nix documentation.

It is by no means complete, the idea is mostly to get the ball rolling
in some way. Upcoming tasks are hinted at in the comments in the
documentation file.
@sternenseemann sternenseemann merged commit 0a66465 into master Jan 14, 2023
@sternenseemann sternenseemann deleted the haskell-nixpkgs-manual branch January 14, 2023 21:33
@ScottFreeCode
Copy link

  • FAQ: Why don't build-tool-depends work with cabal v2 command?

In case this PR's comments get used for future reference, is this issue https://gist.github.com/ScottFreeCode/ef9f254e2dd91544bba4a068852fc81f ?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@ConnorBaker ConnorBaker ConnorBaker left review comments

@teto teto teto left review comments

@maralorn maralorn maralorn approved these changes

@cdepillabout cdepillabout Awaiting requested review from cdepillabout

Assignees
No one assigned
Labels
6.topic: haskell 8.has: documentation This PR adds or changes documentation 10.rebuild-darwin: 0 This PR does not cause any packages to rebuild on Darwin 10.rebuild-linux: 0 This PR does not cause any packages to rebuild on Linux
Projects
Haskell infrastructure in nixpkgs enhancements
Status: Done
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
7 participants
@sternenseemann @teto @cdepillabout @nixos-discourse @ScottFreeCode @maralorn @ConnorBaker