Handling of readme and license files

[Robert Goldman]

I have been out of town and away from my email for a while. Sorry for 
the late response. Checked ASDF code and I think you are right: it would 
make sense to make `:read-file-form` more generally usable than just in 
the `:version` property.

Unfortunately, if we were to do this, it would cause new `defsystem` 
forms to be backwards incompatible, which would be undesirable.

We could probably instead add a `:license-file` `defsystem` option. We 
should think carefully about how this is to be done, though. Probably 
this should *not* point to a file directly, but to a component 
(generally a `:static-file`): that would be desirable because using a 
component already provides a mechanism for specifying the location of a 
source file.

At this point, though, we are starting to get a structure that is so 
fussy that it is likely to cause more problems than it fixes.

I wonder if this is a technical problem at all. Maybe the problem is 
just that developers are not putting the right static files into their 
systems, and the issue is that our social practices need to be fixed, 
not our code. If programmers should be putting license files in as 
static files, maybe we should just be teaching them to do this.

On 14 Oct 2022, at 15:51, Russell Sim wrote:

> Hey,
>
> I'm working with a project that bundles up CL systems, and then copies
> them to a remote host.  To avoid copying unnecessary files, we rely on
> the components and additional-input-files to find all the files needed
> to load the system on the remote host.
>
> I found some ASD files to load on the remote host. These systems are
> expecting to read a long-description, usually a readme file.  All of
> these projects are using reader macros to load this data, and none of
> them declare the file as a :static-file component.
>
> It's also often the case that the license of a project requires a copy
> of the license be shipped with the project. Yet rarely do I see any
> project declaring a :static-file for one in their asd file.
>
> Am I correct in my understanding that using :static-files is this the
> current recommended way to declare these files?
>
> Is there any plan for ASDF to improve the handling of these 2 cases?  
> I
> see other packaging systems often have a special field for the license
> file, and having a :read-file form for the long-descripton much like 
> the
> version field has, would improve handling of these readme's greatly.
>
> At the moment asd authors don't have an easy way to test asd 
> evaluation
> when files like the readme aren't present. Leading to error prone code
> like this.
>
>   :long-description
>   #.(uiop:read-file-string
>      (uiop:subpathname *load-pathname* "README.md"))
>
> I pulled a sample of 800 packages from quicklisp, 95 of them are using
> either uiop:read-file-string (65) or a safer, more verbose
> with-open-file (30) form.
>
> Thank you for your work maintaining this essential system.
>
> Regards,
> Russell Sim


Robert P. Goldman
Research Fellow
Smart Information Flow Technologies (d/b/a SIFT, LLC)

319 N. First Ave., Suite 400
Minneapolis, MN 55401

Voice:	(612) 326-3934
Email:    rpgoldman at SIFT.net
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://mailman.common-lisp.net/pipermail/asdf-devel/attachments/20221020/c68aefa8/attachment.html>