All files in a distribution should be listed somewhere in META6.json (i.e. bin/ and docs/ files)

[ugexe]

Currently bin/ files are not listed in the META6.json data, yet we want to install those files. Right now that is done by automatically including all files found on the filesystem itself under bin/ into an internal-use field 'files'. This is problematic for a couple of reasons:

1. You can't know what e.g. scripts a distribution includes without first extracting whatever archive it is contained within.

2. CompUnit::Repository::Installation expects all bin/ files are Raku. Yet these files often don't have any extension (i.e. bin/zef), so there isn't a foolproof way to guess.

(1) mostly speaks for itself. (2) requires a little more thought - should we allow non-raku bin/ scripts to be installed? If yes, we'd have to store them somewhere else and figure out how to deal with namespace collisions for those items, while still somehow allowing users to set their PATH in a way they can be used. If yes, we not only need to list those files in META6.json but also somehow mark if they are Raku code or not so we don't run CompUnit::RepositoryRegistry.run-scripit("bin/non-raku-script") in the core.

Looking towards the future we also want to install documentation files. For the situation where people keep their rakudoc in their own files we might expect users to list those files in the META6.json somewhere. That is probably a bit naive though, as some users keep their rakudoc inside their modules files. Maybe something that maps namespaces to their docs, like "provides-docs" : {"Text::Foo" : "docs/Text/Foo.pod6", "Text::Foo::DocInModule": "lib/Text/Foo/DocInModule.rakumod" }. Or maybe tooling should just be smart enough to check metadata for an explicit rakudoc file, and if it doesn't exist try to use the pod from the module itself.

[JJ]

This would help with some issues in fez, too.

[vrurg]

like "provides-docs" : {"Text::Foo" : "docs/Text/Foo.pod6", "Text::Foo::DocInModule": "lib/Text/Foo/DocInModule.rakumod" }. Or maybe tooling should just be smart enough to check metadata for an explicit rakudoc file, and if it doesn't exist try to use the pod from the module itself.

provide-docs wins because some docs may not have a reflection in modules. Consider MyMod::ChangeLog, MyMod::CookBook, etc.

[finanalyst]

@ugexe The documentation aspect is now more important because of changes to RakuDoc v2. There is now an explicit schema rakudoc: for links to modules and their documentation.

I'm in favour of:
"provides-docs" : { TARGET-NAME : TARGET-FILE, ... } where TARGET-NAME Is your Text::Foo, and TARGET-FILE is your docs/Text/Foo.pod6

Then in a RakuDoc file we can have L<See method in FOO module| rakudoc:TARGET-NAME>

This is much more flexible than insisting all documentation is under doc/.

However, I think provides-docs is a bit clunky. Perhaps documentation-links might be more intuitive?

[finanalyst]

@ugexe Concerning binary files under bin/: In practice I have included thin raku wrappers to modules with sub MAIN. Also, it is easy to wrap bash scripts in a run or shell, and have the bash script as a RESOURCE. So:

• in practice, it seems to me that constraining the contents of bin/ to raku binaries is not a barrier to what might be wanted
• it provides a method for a module maintainer to detect the OS at run time and to provide alternative scripts for different OS environments (each bat or bash script being in RESOURCES)