Procedure for including libraries in a C program

Hi, I’ve made two threads recently and both of them have kind of centered around this same issue.

I am using the official DDE compiler and the shared Makefile system.

There are multiple libraries on the system, and more can be installed from !PackMan, but I have not yet figured out how to derive from these libraries what needs to be included in my Makefile to make the compiler see these libraries and allow me to #include them in my code.

For example, I have the following in my Makefile right now:

CINCLUDES = -IC:,OSLib:,SFLib:,TCPIPLibs:
LIBS = SFLib:o.SFLib OSLib:o.OSLib32 ${NET5LIBS}

SFLib and OSLib both need me to run a !SetVars obey to make the compiler recognize them. TCIPLibs is included on the system but I never would have known what to put here unless someone on this forum told me (which is exactly what happened) and OSLib and SFLib were described in Steve Fryatt’s tutorial and I was also told what to put there.

Now I want to use the SocketWatch library (from !PackMan), and I need to add something to my Makefile for that to work because just running #include “sockwatch.h” doesn’t work.

I don’t want to pop into the forum every time I want to use a new library and ask someone what to include, I would like to know how I can find this information myself. How can I do that?

Now I want to use the SocketWatch library (from !PackMan), and I need to add something to my Makefile for that to work because just running #include “sockwatch.h” doesn’t work.

Please can you point to exactly what you have installed? The SocketWatch that I know is a module, not a library; there may be some C veneers for it, but they don’t seem to be in the module downloads that I can find, so knowing what you’re looking at would be a help!

The SocketWatch that I know is a module, not a library; there may be some C veneers for it, but they don’t seem to be in the module downloads that I can find, so knowing what you’re looking at would be a help!

SocketWatch 0.06, on the autobuilder, builds from a single ObjAsm file. There is no library nor header file. The source was revealed here on the autobuilder with the -D switch. Having got that source into RISC OS the module did build with the DDE.

Please can you point to exactly what you have installed?

The package available as SocketWatch on !PackMan, and here

According to PackMan, it installed here on my system:
$.System.310.Modules.Network.SockWatch

The SocketWatch that I know is a module, not a library;

I took another look at the descriptions and you’re right, !PackMan and riscos.info do say module instead of library. To be honest I am not sure what the difference is. The descriptions of the package imply that it is supposed to be used by other programs, which is what I assume a library is. I would like to know the difference, and I would like to know how to use it.

SocketWatch came up in my last thread, where Alan Williams mentioned it a couple times saying that I could use it (and also that it was easy to use).

What I’m wondering is, how can I use it? And if I were to run into another module or library somewhere that looked helpful (eg DeskLib), how could I learn how to find this information without asking for help every time?

I would like to know the difference, and I would like to know how to use it.

A library is a collection of code for linking to other code, using the compiler. You’ll usually get a collection of header files and an object file, and when you compile your project the compiler will include the relevant bits of the library’s object file into your executable and fix up all of the function calls so that they get performed using a branch or jump in the “normal” way.

A module is a self-contained program that has been built to run on RISC OS. They’re a very RISC OS-y thing, and can either be self-contained applications (eg. StrongED and Zap are both application modules) or background tasks or collections of routines that provide services for others (eg. the Wimp, which drives the whole RISC OS Desktop, or SocketWatch). They often make functionality available to other applications via SWI calls, which is what SocketWatch is doing. What they’re not is a shared library (except that the Shared C Library is, but we won’t go there for now).

To use a library, you need to give the compiler two pieces of information: where the header files are stored, and where the .o (or .a in Linux parlance) file is stored. There’s no fixed way of doing this that I’m aware of (as I note in my tutorial), but there’s a standard-ish approach which is to provide an Obey file which can be run to set some system variables up. For example, OSLib has SetVars, which resides in the root of the library folder structure and reads

| OSLib's SetVars
| Sets the directory and path variables for OSLib.
Set OSLib$Dir <Obey$Dir>

| The OSLib: path is the presently preferred style for include files;
| You always need to use this as the link path.
Set OSLib$Path <OSLib$Dir>.

If you look in the OSLib folder, you’ll see that it contains

+ SetVars
+ o
| + OSLib32   < The object file
+ oslib
  + h
    +         < All of the header files

So when SetVars sets OSLib$Path to the value of Obey$Dir and a trailing dot, it’s setting it to point to the OSLib folder that it’s within, wherever it happens to be on your disc at the time (as Obey$Dir points to the folder containing the Obey file that’s currently being executed). Path variables are useful things: if you set MyPath$Path to “ADFS::HardDisc.$.C.Libs.OSLib.” (note the trailing dot), then when you give a filing system “MyPath:o.OSLib32” it will actually look for “ADFS::HardDisc.$.C.Libs.OSLib.o.OSLib32”.

So when you add

CINCLUDES = -IOSLib:

to your Makefile, you’re telling the compiler to search within the OSLib folder for header files. You then write something like

#include "oslib/wimp.h"

in your source file, and the compiler starts in OSLib, looks in the oslib folder because the #include contains it, then in h and finally locates the wimp file (because Norcroft takes “wimp.h” and turns it into a folder/file combo of “h.wimp” for “historical reasons”).

In a similar vein, when you add

LIBS = OSLib:o.OSLib32

to your makefile, you’re telling the compiler to link against the file inside the OSLib folder, then down into o, and finally use the OSLib32 file.

When you find a new library, you need to look at the documentation (if there is any) to see if it suggests how to reference it to the compiler. If that fails, look for Obey files that might help. If that fails, I’d suggest writing your own Obey file to set up a Path Variable. I use a tool called LibFolder, but I’ve never got around to releasing it as a “thing”.

Using modules is different. Once a module is in memory, you can usually access the SWIs that it contains from your code. How you do this depends on the module:

• If it’s one that OSLib supports, use OSLib.
• If it isn’t, look for a library or veneers that might wrap up the SWI calls for you.
• If that fails, you can use _kernel_swi() or _swix() to make the calls: https://www.stevefryatt.org.uk/risc-os/wimp-prog/moving-to-c

To get the module into memory, you can start by double-clicking on the module before you test your code – but that quickly becomes tedious. The correct way is to *RMEnsure the modules from an Obey file, such as your application’s !Run file (see https://www.stevefryatt.org.uk/risc-os/wimp-prog/creating-an-application-directory), and if you’re using the Shared C Library then you really should have a !Run file like the one in that link anyway.

If PackMan installs SocketWatch somewhere like !System for you, then you RMEnsure it from there. Otherwise, you’ll probably need to include a copy inside your application directory. I’ve never used SocketWatch, so I’ll let someone else advise on that one.

What I’m wondering is, how can I use it? And if I were to run into another module or library somewhere that looked helpful (eg DeskLib), how could I learn how to find this information without asking for help every time?

The first thing to do on the system is to use the CLI help.

CTRL-F12 with open a task window with a CLI
“help” (or h.) will list the help info
“h. modules” will list out the loaded modules – note that many are integral to the base OS¹, and new ones you install (like Socketwatch) will also be listed as they are extending the OS.

“h. Filer” will list the commands provided by that module

and h. socketwatch similarly.

and h. socketwatch similarly.

Although these will give you the * commands, while for use in a C program you’ll ideally want the SWIs. For those, read the documentation (which there hopefully is).

Thanks for the detailed response!! This is making a lot more sense to me now. I am also happy to learn there is a help function for the command line.