[racket] pkg/info.rkt documentation

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