[I6] infglk.h

I’m writing a platform independent I6 extension that uses the glk API, and I’d like to discuss my experiences with infglk.h and make a recommendation:

[rant]Here’s a chronology of events:

  • I read through Adam Cadre’s Gull document as a quick overview and refresher on glk/glulx programming. He recommends using infglk, a library that wraps direct glk calls (e.g., @glk 66 :wink: with meaningfully named functions (glk_stream_open_file();). Seems like a good idea that will improve code readability.
  • I visited the ifarchive and found infglk.zip, by John ‘katre’ Cater, among the I6 library contributions. The archive contained: func.txt (a list of glk function specifiers and the functions to which they correspond, taken from zarf’s glk spec), glk.h (zarf’s glk header, unmodified), glk2inf.pl (a perl script by katre, the meat of this extension), infglk.h (the output of the glk2inf.pl tool), and test.inf (a small test program that includes infglk.h). The idea is to run glk2inf.pl with func.txt and glk.h as input, producing infglk.h, which can then be included in one’s I6 project.
  • I noticed that infglk was 5 years old and based on glk version 0.7.3. I wondered if the glk api had changed in the interim. I checked the archive and saw that a newer version of glk, 0.7.4, now existed. The changes appeared to be minimal and backwards compatible, but I thought “why not use the latest and greatest if possible?”
  • I downloaded glk.h and the glk spec for 0.7.4, created a new func.txt from the spec, ran glk2inf.pl, and produced a new infglk.h based on glk 0.7.4.
  • I wondered why this wasn’t on the ifarchive and considered putting it there myself. I figured that I should probably get permission from katre if I wanted to upload a zipfile containing his tool along with the new infglk.h, so I searched these forums for any trace of him or discussion of infglk.h.
  • I found some discussion circa 2011 (“remember to get the latest infglk.h, not the one in the IF Archive but the one in zarf’s github thing”) indicating that infglk had been incorporated into I7’s I6 template layer and that zarf was now maintaining a github repo containing a tool called parse_dispatch.py that replaces glk2inf.pl and produces a similar infglk.h.
  • I experienced a complete failure to be surprised as I reflected on my recent experiences locating the latest versions of various I7 extensions.
  • I grabbed the infglk.h from zarf’s github repo and saw that it contained some new API elements that appear to be destined for a future 0.7.5 glk release. Pleased that I had now located the actual latest and greatest, I incorporated it into my project.
  • Compiling my project, I discovered that the parse_dispatch.py version of infglk.h has some drawbacks relative to the old glk2inf.pl version.
    [list]
    [*] It’s doesn’t have a System_file; declaration in it, so compilation produces many warning about unused constants and functions
  • It doesn’t conditionally compile based on whether TARGET_GLULX is defined. Not a big deal, since the inclusion site can be protected instead, but it’s still 2 lines of code to write.
  • It doesn’t contain guards against multiple inclusion. This is more of a big deal from the standpoint of an extension author, because I can’t control what my clients will do. I can tell them not to include infglk.h because my library does, or tell them that, if they do, they should include it before including my header, but it’s one more item on a list of fiddly “in order to use this extension, you need to do x or not do y” things, when I’d rather that the list consist entirely of “include my header file and go about your business”.
    [/:m]
    [
    ] So, I edited the new infglk.h to include these things, leaving me with this Frankensteinian hybrid of the preamble of the old infglk with the body of the new infglk rather than the purely autogenerated file that I’d like. It also makes it slightly less clear what I need to do for licensing/compliance in order to ship the resulting infglk.h file with my extension other than to clearly state what I’ve done, apply credit liberally, and cross my fingers.[/*:m][/list:u][/rant]
    Reading through more of the “infglk” search results here, I came across a post from DavidG in which he says, for slightly different reasons than my own:

Yes, can we? It’s already incorporated into I7. Why not integrate it into the I6 library and make the lives of I6 programmers easier as well?

I think there’s also a broader question about the role of I6 and its library these days. Does it exist strictly to support I7, or does it exist as language in its own right that should continue to evolve (in a way that’s considerate of I7’s dependence on it) to support traditional (non-natural language) IF programming targeted at the z-machine and glulx.

I went ahead a few months ago and added infglk.h to the library repo.

Awesome. I had been looking at the version of the lib in the inform-6.33.1-b3 tarball rather than the latest from git.

I see that the version in the lib repo is an older glk2inf generated one (it has gestalt_Foo constants ranging from 0 to 14, while the latest parse_dispatch one has them ranging from 0 to 23). It might be worth updating, although we then run into the issues (System_file, #ifdef TARGET_GLULX, multiple inclusion guards) that I mentioned in my rant.

It’s probably worth tarring up a version of the dispatch_dump stuff and uploading it to if-archive/infocom/compilers/inform6/library/contributions/glulx along with a description that says something like “This obsoletes infglk.zip. See the github repo at for the latest dev version of this package.”

I definitely recommend everybody use my latest infglk.h content everywhere. It’s true that it’s somewhat ahead of the published Glk 0.7.4 spec, but the spec will catch up eventually.

Putting it into the I6 library is the right idea as far as I’m concerned.

My version evolved in an environment where the I6 libraries were not being updated but I7 was. My audience was mostly Graham. That’s why it doesn’t have System_file (not appropriate for an I7 tempate file) or conditional checks (I7 took care of that).

I can tweak the generator, but how should I do this?

  • It’s no problem to add #ifdef TARGET_GLULX.
  • Multiple inclusion guards shouldn’t matter if it’s in I6lib now.
  • System_file is the odd case. Should I put that declaration under an #ifndef that applies to the I7 environment? I think that will work.

Alternatively, I could generate infglk6.h and infglk7.h.

I could, but it’s one more thing for me to forget to update… I like keeping things in as few places as possible.

I think the former is best, under the “don’t repeat yourself” principle. Two distinct files containing duplicate info could go out of sync with one another. It’s unlikely, but no point in risking it if having a single file is equally viable.

Understandable. Maybe just augment infglk.zip’s description with “Note: this is outdated. Go here instead: ”

I’d prefer a single include file with ifdefs.

I’ve updated github.com/erkyrath/glk-dev/tre … patch_dump with these changes.

Thanks!

Might want to stick in

#ifdef INFGLK_H;
#endif;

or some other use of INFGLK_H to shut up the compiler.

Rearranged the code to avoid that.

Ah, right. Taking advantage of the System_file is better than adding extra crud.

Thanks again.