RISC OSLib documentation?

I can find no documentation on RISC_OSLib. Is there any? I have looked in PRMs, DDE manuals and the internet.
Please don’t suggest using another library – I am trying to understand code which uses it!

I can only find the headers in DDE.AcornC/C++/Export.Lib.RISC_OSLib, but they are rather cryptic and do not answer my questions.

In particular I am looking for descriptions of functions like wimpt_init, res_init, resspr_init and template_init and if/how they use Myprog$Dir and Myprog$Path variables.

It’s in the Acorn C/C++ guide.

No, it isn’t.
I’m sure it used to be…

Just like back in the olden days, the only documentation is the source: https://gitlab.riscosopen.org/RiscOS/Sources/Lib/RISC_OSLib/-/blob/master/rlib/c/wimpt

Don’t think it was ever part of any Acorn release Rick, it was usually punted to devs on a floppy saying use at your own risk.

See Rick’s notes below. Still read the source as that tells you current behaviour! Assuming Martin is going to be linking an updated program against a DDE RISC_OSLib not some archaic version.

Get the “ANSI C release 4” PDF from 4corn (47.64MB).

Page references are to the PDF’s pages, not what’s marked on the page itself.

wimpt_init: p326, I don’t think this uses the variables? Just stores the name and calls wimp_taskinit plus adds an exit handler.

res_init: p263, this sets the name used in resources, so for MyProg$Dir, you’d call res_init with “MyProg”.

resspr_init: p264, takes no parameters and is described as “This function reads in your sprites.”, so I’m guessing it’ll be looking for Sprites[22] according to the previously set resource path.

template_init: p273, says nothing of use. Again, I think this just sets up some pointers, and it’s the readfile that will be using the resources name (though it, too, doesn’t say).

Don’t think it was ever part of any Acorn release Rick.

A vast section of the C v4 guide is a description of the library. I clearly remember it as I was in a hospital waiting room reading it, and thinking that it… could have been a lot better. I’m being polite.

Clearly a mistake to have documented it then! Toolbox was well in use (within Acorn at least) by that time. Think we only ever got C v4 on floppies, no docs.

Looking at the source now.

wimpt_init sets “programname”.

res_init also sets “programname”.

res_openfile calls res_findname to try to construct a name, which appears to be “programname:leafname” and if that fails (no path), will revert to “programname$Dir>.leafname”.
There appears to be some weirdness in that if the file name is “r” or “r+”, then it’ll also try to open the determined name with the country number as a suffix (so I’m gessing “Templates4” for France?

resspr_init calls res_prefixnamewithdir to try the icon themes, and finally just looking for a sprite file. The name is constructed using the programname previously set. It uses Wimp_Extend to determine the Sprite suffix (22, 11, etc) and tries a few different options, loading the sprite file when one works.

• With theme as an app path
• With theme as an app dir
• Just Sprites as an app path
• Just Sprites as an app dir

template_init actually does read the file. It simply calls res_findname to try to locate the file, so behaviour already discussed above.
Possibly worth noting that there’s a hardcoded 40 byte buffer used to cache the filename, which ought to be plenty but since nothing actually checks…..

Clearly a mistake to have documented it then!

The documentation for RISC_OSLib alone is 156 pages. There’s no mention whatsoever of Toolbox.

Toolbox was well in use (within Acorn at least) by that time.

Cv4’s manual dates from early 1991. When was Toolbox created? The comments at the top of various files suggest that it was mostly written by IDJ (core) and TGR (gadgets) from Summer 1993 to Spring 1994. So maybe you’re misremembering, unless they had some prototype version kicking around to test the viability of making a toolbox system?
Unfortunately there’s no Blacklog file, and since history is in CVS/Git and that’s not retained in any meaningful manner when downloading a tarball and the recorded history only goes back to circa 1997 when it was imported from a “cleaned 360 CD”…

Thanks to Stuart & Rick for very helpful suggestions. Some further study required.

I find it appalling that the only ‘documentation’ supplied with the current DDE about the included RISC_OSLib are the header files. I was aware I might have to resort to the source, but that is not for the faint-hearted, and in some parts requires knowledge of the defines used to actually generate the library!

The Release 4 manual looks interesting, and I will have a better read later.

A major obstacle to understanding most C I try to read is that for every function called I have to establish whether it is defined somewhere in the code, or in an external library. Then comes the battle to decide which library, and what (if any) documentation. Does not endear C to me. I spent many decades ensuring that any code written was understandable and maintainable by others.

Is there any software which can analyse a large chunk of C and produce function call lists or diagrams?

Presumably the compiler can do that? Most compilers that are any good should be able to generate a list of variables used, where defined and the values of any constants. Also a cross reference listing of any functions used and where called from and where defined.

A major obstacle to understanding most C I try to read is that for every function called I have to establish whether it is defined somewhere in the code, or in an external library. Then comes the battle to decide which library, and what (if any) documentation. Does not endear C to me. I spent many decades ensuring that any code written was understandable and maintainable by others.

To be fair, that’s not C’s fault. It’s quite possible to have the same issues with BASIC, for example. Badly-written anything is hard to follow…

In anything that I’ve written, you’ll usually find that the function, global variable and constant names start with the name of the file that they belong to. I can’t think whose style guide I learned that from, but it helps a lot!

That said, I find VSCode’s Shift-Ctrl-F with a variable, function or whatever’s name highlighted fairly helpful in tracking down where the definition is. The fact that I can pull libraries in as folders within the overall project helps. StrongED should do something similar, I think — or perhaps TextSeek? To be honest, it’s stuff like this that drove me to use an IDE on a platform that wasn’t RISC OS…

Is there any software which can analyse a large chunk of C and produce function call lists or diagrams?

I tend to use Doxygen, but you do need to have written the comments in order for it to be useful. It might do call graphs without them, though.

Using MS VC++ 6 one just hits a key to go to the definition of a function (F12, and shift+F12 for references)- even from libraries – as long as the programs are compiled with the correction options. There are open source standalone tools that analyse C programs. I didn’t mostly bother using the RISC OS version, I just used grep.