rtfm: init at 0.2.2

[sund3RRR]

Description of changes

It's a dash/docset reader with built in documentation for Crystal and GTK APIs. It's written in Crystal using GTK4 bindings.
https://github.com/hugopl/rtfm

Things done

• Built on platform(s)
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• For non-Linux: Is sandbox = true set in nix.conf? (See Nix manual)
• Tested, as applicable:
  • NixOS test(s) (look inside nixos/tests)
  • and/or package tests
  • or, for functions and "core" functionality, tests in lib/tests or pkgs/test
  • made sure NixOS tests are linked to the relevant packages
• Tested compilation of all packages that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage
• Tested basic functionality of all binary files (usually in ./result/bin/)
• 23.11 Release Notes (or backporting 23.05 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.

[sund3RRR]

@drupol, @SuperSandro2000 could you please review this PR? It's been 3 days and no one wants to :(

[drupol]

Suggested change

	adw1_ver = "1.3.3";
	adw1_version = "1.3.3";

[drupol]

Suggested change

	rev = "refs/tags/${finalAttrs.adw1_ver}";
	rev = "refs/tags/${finalAttrs.adw1_version}";

[drupol]

Suggested change

	gtk4_ver = "4.11.4";
	gtk4_version = "4.11.4";

[drupol]

Suggested change

	rev = "refs/tags/${finalAttrs.gtk4_ver}";
	rev = "refs/tags/${finalAttrs.gtk4_version}";

[drupol]

Suggested change

	pango_ver = "1.50.14";
	pango_version = "1.50.14";

[drupol]

Suggested change

	rev = "refs/tags/${finalAttrs.pango_ver}";
	rev = "refs/tags/${finalAttrs.pango_version}";

[drupol]

Could you please add a comment on why this patch is required, for each patch in this list?

[sund3RRR]

Sure

[drupol]

Could you please add the platforms attribute with proper values? So we know on which architecture this software is available.

[sund3RRR]

Can i set platforms = [ "i686-linux" "x86_64-linux" ];; because i can't test on aarch64 and darwin?

[drupol]

Just set the platforms the software you're trying to add supports, then the CI will test on these architectures.

[sund3RRR]

I set platforms.linux. Theoretically, it might run on darwin, maybe i'll setup OpenCore later on my PC.

[drupol]

Or you can ask to the Darwin maintainers team, they are quite reactive. Set it correctly and we'll ask them.

[sund3RRR]

Done. if I understand correctly how to do it

platforms = platforms.linux ++ platforms.darwin;

[drupol]

Yes!

[SuperSandro2000]

This should also get a meta section

[SuperSandro2000]

Suggested change

doInstallCheck = false;

only one should be required here

[SuperSandro2000]

gobject-introspection goes to nativeBuildInputs

[SuperSandro2000]

Do we really must pin those 3?

[sund3RRR]

I think so, because they are marked as dependencies on the project's github, that is, the author assumes that during the process of building the program, all the documentation is present in the system.

- Offline crystal api documentation for Crystal docset generation.
- Offline Gtk api documentation for Gtk4, Gdk4, Gsk4, libAdwaita and Pango libraries for GTK4 libraries docset generation.

We can build a program without documentation at all, but in this case rtfm will be useless. It also makes no sense to set part of the documentation, since in this case the user himself will have to generate docsets from sources.

[SuperSandro2000]

I didn't mean that we could remove them but if we could use the versions from nixpkgs.

[sund3RRR]

I didn't find docs in gtk/pango/libadwaita nix packages.

[SuperSandro2000]

It should get pname+version even if version is just dummy or from rtfm or so

[SuperSandro2000]

Suggested change

mainProgram = "rtfm";

that's already the default

[SuperSandro2000]

Suggested change

platforms = platforms.linux ++ platforms.darwin;

please check if buildCrystalPackage implies this

[SuperSandro2000]

Suggested change

	tar -xf ${crystal-docs} && mv crystal-${crystal_doc_version}-docs/ crystal-docs/
	tar -xf ${crystal-docs}
	mv crystal-${crystal_doc_version}-docs/ crystal-docs/

[SuperSandro2000]

Should we passthru this?

[sund3RRR]

Like this?

let
  passthru = {
    gtk-docs = callPackage ./gtk-docs.nix { };
  };
in

[SuperSandro2000]

normally we inherit into passthru so that overriding passthru is not changing things

[sund3RRR]

@hugopl could you help with one point? I generate gi docs using gi-docgen. The GDK/GTK docs have a dependencies block, that has hard-coded dependency URLs.

Is there a way to change Browse documentation link to local docsets?

  [dependencies."GObject-2.0"]
  name = "GObject"
  description = "The base type system library"
  docs_url = "https://docs.gtk.org/gobject/"

  [dependencies."Gio-2.0"]
  name = "Gio"
  description = "GObject Interfaces and Objects, Networking, IPC, and I/O"
  docs_url = "https://docs.gtk.org/gio/"

  [dependencies."cairo-1.0"]
  name = "cairo"
  description = "A 2D graphics library with support for multiple output devices"
  docs_url = "https://www.cairographics.org/manual/"
  ...

[sund3RRR]

After force-pushing last commit, i noticed some checks were failed.

ofborg-eval — This PR does not cleanly list package outputs after merging.

 error: attribute 'devdoc' missing

       at /var/lib/ofborg/checkout/repo/38dca4e3aa6bca43ea96d2fcc04e8229/mr-est/ofborg-evaluator-7/pkgs/applications/misc/rtfm/default.nix:67:20:

           66|
           67|     for file in "${gtk4.devdoc}"/share/doc/*; do
             |                    ^
           68|       ln -s "$file" "gtk-doc/$(basename "$file")"

It happens because gtk4.devdoc output depends in x11Support optional argument

outputs = [ "out" "dev" ] ++ lib.optionals x11Support [ "devdoc" ];

So, maybe i need to override x11Support = true?

[SuperSandro2000]

So, maybe i need to override x11Support = true?

seems like it

[sund3RRR]

So, maybe i need to override x11Support = true?

seems like it

Nothing happened, i don't know why and how to fix it

[SuperSandro2000]

Suggested change

	substituteInPlace Makefile --replace "crystal run src/create_crystal_docset.cr" "crystal src/create_crystal_docset.cr ${crystal}/share/doc/crystal/api/"
	substituteInPlace Makefile --replace "crystal run src/create_gtk_docset.cr" "crystal src/create_gtk_docset.cr gtk-doc/"
	substituteInPlace Makefile \
	--replace "crystal run src/create_crystal_docset.cr" "crystal src/create_crystal_docset.cr ${crystal}/share/doc/crystal/api/" \
	--replace "crystal run src/create_gtk_docset.cr" "crystal src/create_gtk_docset.cr gtk-doc/"

[hugopl]

Is there a way to change Browse documentation link to local docsets?

I can reproduce this on Archlinux too and created an issue.

[SuperSandro2000]

Suggested change

	(gtk4.override { x11Support = true; })
	gtk4'

[SuperSandro2000]

Suggested change

	}:
	}:
	let
	gtk4' = gtk4.override { x11Support = true; };
	in

[SuperSandro2000]

Suggested change

	for file in "${gtk4.devdoc}"/share/doc/*; do
	ln -s "$file" "gtk-doc/$(basename "$file")"
	done
	for file in "${pango.devdoc}"/share/doc/*; do
	ln -s "$file" "gtk-doc/$(basename "$file")"
	done
	for file in "${libadwaita.devdoc}"/share/doc/*; do
	for file in "${gtk4'.devdoc}"/share/doc/*; do
	ln -s "$file" "gtk-doc/$(basename "$file")"
	done
	for file in "${pango.devdoc}"/share/doc/*; do
	ln -s "$file" "gtk-doc/$(basename "$file")"
	done
	for file in "${libadwaita.devdoc}"/share/doc/*; do

Those are taken directly from the inputs, not buildInputs where you did the override

[sund3RRR]

@SuperSandro2000 it works, all checks passed

[hugopl]

@sund3RRR would you mind in creating a PR for rtfm README with the instructions to install this NixOS package?

[sund3RRR]

@sund3RRR would you mind in creating a PR for rtfm README with the instructions to install this NixOS package?

Sure, but these instructions will be useless until this PR is approved

[hugopl]

Yeah, sure, I mean, when it gets approved/merged.

[drupol]

Thanks for your contribution, it's ok for me now.

[hugopl]

I can fix that upstream.

[hugopl]

Usually distros run these command for any packages that install files on specific dirs used by these commands.

[hugopl]

Why you guys don't use the gi-crystal that the project depends on? Do you guys have a gi-crystal nix package? if so, why?

[sund3RRR]

I packed gi-crystal in nixpkgs when I packed the collision. You can see these PR's: #243914
#242681
There is an explanation why we decided to do it this way.

Shortly, nix collects crystal dependencies in separated derivations, then creates a symlimks on it in lib/ directory of project. I am creating a patch when packing gi-crystal to make it work with symlinks. The main problem is that all derivations in nix store are read-only and changes in one derivation will change drv hash and all hashes, that depend on it. When we run ./bin/gi-crystal it fails with error Permission denied, because it cannot write to read-only directory.

So, gi-crystal in nixpkgs works differently due to this nix features. All you need to do is add gi-crystal in build inputs, then run gi-crystal. It will scan lib/ directory with all symlinks, then generate all bindings in lib/gi-crystal directory and copy self package to this.

[drupol]

Shortly, nix collects crystal dependencies in separated derivations, then creates a symlimks on it in lib/ directory of project. I am creating a patch when packing gi-crystal to make it work with symlinks. The main problem is that all derivations in nix store are read-only and changes in one derivation will change drv hash and all hashes, that depend on it. When we run ./bin/gi-crystal it fails with error Permission denied, because it cannot write to read-only directory.

Jumping into the convo here... How about copying the gi-crystal derivation into the current rtfm directory and then use it ? That would fix both issues. You will be re-using the existing gi-cristal and it's directory is writable since you copied it into the rtfm build directory.

WDYT? Is it feasible?

[sund3RRR]

How about copying the gi-crystal derivation into the current rtfm directory and then use it ?

This is exactly what I did when packing gi-crystal. But I actually automated this action so as not to do it constantly for different packages.

I think that's better, don't you?

https://github.com/NixOS/nixpkgs/pull/243914/files#diff-1a3ec3be7dadadd498d82613b7eaba4d02f11f8470913c5cbdb7d54932c63954R53

[drupol]

What I mean is to copy the output of gi-crystal into rtfm and then use it.
Once the compilation is over, you delete it and only copy the relevant rtfm files in $out.

WDYT?

[sund3RRR]

What I mean is to copy the output of gi-crystal into rtfm and then use it.
Once the compilation is over, you delete it and only copy the relevant rtfm files in $out.

I'm sorry but I don't understand what's the difference. If we want to make it work without patching Makefile, then we need to do several steps:

mkdir lib/gi-crystal
cp -r ${gi-crystal}/* lib/gi-crystal
mkdir bin/
mv lib/gi-crystal/bin/gi-crystal bin/
chmod +w lib/gi-crystal/src/auto

I think it is just unnecessary steps to be done on each package requires gi-crystal.

And even if we do that, we still have to patch this to remove shards install command, because it will crash building due to cannot fetch remote host github.com something like this, I definitely don't remember what that error sounds like.

WDYT?

[drupol]

I don't see the issue to do that all the time. I prefer that than patching the src.

But anyway, I was just passing by here thinking to provides new ideas, but I see that you already studied the question so I won't bother. I never used gi-crystal this is the reason why I might be wrong too.

[sund3RRR]

I don't see the issue to do that all the time. I prefer that than patching the src.

But anyway, I was just passing by here thinking to provides new ideas, but I see that you already studied the question so I won't bother. I never used gi-crystal this is the reason why I might be wrong too.

Thanks for suggesting solutions to this problem. Patching sources was the reason why I didn't want to pack gi-crystal. My best idea is to make gi-crystal portable, this fits well with the nix ideology, but changes program behaviour.

Speaking of using gi-crystal, I understand the steps involved in implementing your idea. But others may not realize that you need to copy the gi-crystal directory, mv gi-crystal binary and change the write permissions.

[drupol]

Ok... sad but ok.

It's weird that it needs to write in the gi-crystal directory.

[hugopl]

Looks like you guys are re-doing what shards already does, but at a package level. I mean... if derivations means a packaged code.

[hugopl]

I added this change upstream at hugopl/rtfm@8833114

[hugopl]

I can't add this upstream or it will break ArchLinux package.

[hugopl]

Could you explain this error? why does it happen? So I can fix it upstream too.

[sund3RRR]

It happens because rtfm copies docs from nix derivation, but all files in nix-store are read-only, so at first we need to add write permissions to the copied file. This error is nix-specific, but it cannot break rtfm on other distros i think.