[racket] pkg/info.rkt documentation

I had the same troubles figuring out packages. I think this is one of the
weaker parts of the documentation, because it seems a bit decentralized on
the topic and extensively covers the details but doesn't have a
simplification for the common case - a documented and tested package in a
github repo. Perhaps a more thorough walkthrough specifically for this
setup would be useful to have?

On Thu, Jan 1, 2015 at 9:54 PM, Alexander D. Knauth <alexander at knauth.org>
wrote:

>
> On Jan 1, 2015, at 11:12 PM, Brian Mastenbrook <brian at mastenbrook.net>
> wrote:
>
> > I'm feeling a bit dense and/or blind. Is there documentation for the
> info.rkt format that raco pkg expects? I managed to make something that
> works by cribbing off of an existing package,
>
> I felt exactly the same way, and I did the same thing (but still managed
> to get some things wrong), but then did manage to get it, and it does make
> sense.
> Though for me one extra complicating factor was that I was trying to
> include scribble documentation.
>
> But as I understand it:  (If I’m wrong about anything please correct me)
>
> > but I'm not sure what (define collection 'multi) means (or what the
> alternative is),
>
> (define collection ‘multi) means that, if it’s for example a github repo
> (call it A), then there would be a folder within the repo (call it B) that
> would be the collection, and files within that collection (call one of them
> C.rkt).
> So you have a repo called A, a folder within that called B, and a file
> within that called C.rkt, and if the package A is installed, you could
> reference C.rkt by (require B/C).  If there is a main.rkt in the B folder,
> then that can be referenced by either (require B/main) or just (require B)
> There would be two info.rkt files in this setup.
> At the “top level” of the repo, outside of the collection, there would be
> the info.rkt for the package, which would have the (define collection
> ‘multi), the (define deps ….), and other Package Metadata
> http://docs.racket-lang.org/pkg/metadata.html
> Inside the collection, there would be the info.rkt for the collection,
> which would have the (define scribblings ….) and things like that if you
> want them http://docs.racket-lang.org/raco/setup-info.html
> There could be multiple of collections, which is why it’s ‘multi, but
> there doesn’t have to be.
>
> The alternative to (define collection ‘multi) is to have one less
> directory layer, for example in a repo called A, where there is one folder
> that is also called A, it could make sense to just take everything in the A
> folder and put it into the “top level” of the repo, and then you would put
> (define collection “A”) in the “top level” info.rkt, which now serves the
> purpose of having the Package Metadata and the scribblings etc.
> So now you have a repo called A, and a file within that called C.rkt (at
> the “top level” of the repo), and you could reference C.rkt by (require
> A/C), and if there were a main.rkt in the “top level” of the repo you could
> reference that with either (require A/main) or just (require A).
>
> If you’re being technical, the repo name doesn’t actually matter for the
> (require A/C) as long as you put (define collection “A”) in the info.rkt,
> but I think it starts to get a little confusing if you start to do that.
> It’s nice to have a definite place in the code where it tells the pkg
> system to set up the files in the repo as if they were in a folder called
> “A”, and that’s the (define collection “A”), but I think it makes more
> sense if the repo name, the collection name, and the package name are the
> same.
>
> > nor how to figure out what should go in deps beyond "base". Did I miss a
> "pkg for dummies" document?
>
> Well, if your package depends on for instance rackunit, then you would
> want to put “rackunit-lib” in the deps, because in the documentation for
> rackunit, it shows package: rackunit-lib to the right of the (require
> rackunit) http://docs.racket-lang.org/rackunit/api.html
> If there are other modules your package depends on, then you would look up
> their documentation and look at what package provides them, and put those
> packages in the deps.  There are some that can go in build-deps instead,
> but I’m not sure what the rules are for that, and if they’re in the deps
> that’s fine.
>
> I hope I wasn’t too over- or under-assuming.
>
> > --
> > Brian Mastenbrook
> > brian at mastenbrook.net
> > http://brian.mastenbrook.net
> > ____________________
> > Racket Users list:
> > http://lists.racket-lang.org/users
>
>
> ____________________
>   Racket Users list:
>   http://lists.racket-lang.org/users
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.racket-lang.org/users/archive/attachments/20150101/1acf375f/attachment.html>