-
Notifications
You must be signed in to change notification settings - Fork 106
Description
It would be good to provide easy ways for users to showcase how to use JLLs. Right now we spit out a pretty bland example usage with fake products, but this can be improved upon if authors so desire. I'm thinking there should be a per-Product
optional field that takes in a usage example. I'm thinking perhaps what we can do here is to give the opportunity to provide something like a little "doctest" for JLLs; not only can we use this as a way to provide documentation, but we can also run it to ensure that the JLL itself is working.
So now the question is, what is the API? Perhaps something as simple as the following:
products = Product[
FileProduct("src/data.txt", :data_txt; usage="""
str = read(open(data_txt, "r"))
"""),
LibraryProduct("libdataproc", :libdataproc, usage="""
data_lines = "this is a test\nline two of my test!"
ccall((libdataproc, :count_characters), Cint, (Cstring, Cint), data_lines, length(data_lines))
"""),
ExecutableProduct("mungify", :mungify_exe, usage="""
mungify_exe() do exe_path
run(`$exe_path --input=$(data_txt) --find-all=jlbuildbot`)
end
"""),
]
These would get integrated into the README.md generation, and they would also get run when building a platform that is compatible with the host platform, to ensure that the products work at least as well as the author is claiming they should. We wouldn't check that output matches or anything like that like a normal doctest (although we would do a using Test
beforehand, in case someone wanted to do that) but the idea here is just to give some guidelines to what someone can do with this package.