[Pharo-users] Pumping FFI documentation [WAS] FFI beginner question

Guillermo Polito guillermopolito at gmail.com
Tue Sep 24 04:34:08 EDT 2019


Hi Ted,

I split this in a separate thread to avoid noise :)

> El 23 sept 2019, a las 23:14, Brainstorms <wild.ideas at gmail.com> escribió:
> 
> Guillermo,
> 
> I'm interested in helping, but at this point, I think I'd be most helpful
> working at improving documentation (mainly editing) rather than working on
> Pharo code itself.  (I'd like to work toward that, though.)  

I’ve been doing a pass on the structure, and I was thinking on a rough structure as follows:
 1) Intro to FFI (callouts, function and library lookup, intro to value marshalling)
 2) Marshalling (sending arguments, literal arguments, more on marshalling, basic C types: ints, floats, pointers and how they are transformed to pharo objects and vice-versa…)
 3) Complex types: strings, unions, arrays, opaque types
 4) Derived types on the Pharo side: How to design nice classes with all this
 5) Callbacks
 6) Memory management

I did already a pass on 1), and I got blocked in 2), though I want to release a version of it this week.

If you’re up for it, there are several things we can do:
 - review the english :)
 - give feedback on what is missing, what is not understandable, what can be explained better
 - testing the examples?

> 
> I'm still a newbie with Pharo, but I am a good writer/editor.  And I expect
> that working with Pharo documentation would be another means of increasing
> my knowledge of the Pharo ecosystem -- so that's additional incentive for
> me.

Cool :)

> I gather that the PDF books are written using Pillar, which I know nothing
> about.  Are there resources & guides for this tool/format that would help me
> learn how to make & edit these kinds of documents?

Pillar is a markup syntax (from Pier’s CMS, if you know it).
https://github.com/pillar-markup/pillar <https://github.com/pillar-markup/pillar>

Pillar comes with a document model, parser and generators to html, pdf (through latex), and others…
In Pillar’s readme there are the installation instructions + usage.

If you check the travis file in the ffi booklet repository

https://github.com/SquareBracketAssociates/Booklet-uFFI/blob/version2/.travis.yml <https://github.com/SquareBracketAssociates/Booklet-uFFI/blob/version2/.travis.yml>

You’ll see it is built with pillar 7.4.1. In other words

# install pillar
$ git clone https://github.com/pillar-markup/pillar.git -b v7.4.1
$ cd pillar && ./scripts/build.sh && cd ..

# go into the booklet repository and build the pdf
$ ./pillar/build/pillar build pdf

Although you’ll need a mostly up-to-date latex version (latexmk required, plus several other packages, check Pillar’s readme)

> Also, I've never contributed to an open source project; Pharo seems to be a
> good place to start doing so.  I see that most of the documentation, web
> pages, booklets, etc. are in English so there's the advantage that English
> is my first language (and I actually paid attention in school  :^).  I'm
> also aware, from experience, that Documentation is rarely the first choice
> for developers to apply their time & enthusiasm…

And it’s super important nevertheless ^^.

Guille
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.pharo.org/pipermail/pharo-users_lists.pharo.org/attachments/20190924/507eb290/attachment.html>


More information about the Pharo-users mailing list