How to create libraries ?

Bean

Since I know very little about C, I was waiting for the beta to be released before I jump in.
But now I'm here and ready to get to work.

Can you explain step-by-step how I create a library of functions ? I know there is a .h file and a .c file, but I can't figure out how to get my code to use them ?

For example take a program with a function in it and show how to break that function into a seperate library.

Thanks,
Bean

David Betz

Hi Bean!

It's great to hear that you're interested in trying Propeller GCC! Can you say how you'd like to create and use these libraries? Do you want to do this using SimpleIDE or command line tools? I can help with using the command line tools but Steve will have to say how you go about creating libraries using SimpleIDE. I'm pretty sure that it is easy to *use* libraries with SimpleIDE but I don't know what needs to be done to create them.

Welcome aboard!
David

Bean

David,
Yeah, I'm pretty excited about learning C after all this time.
From what I understand, you put the function prototypes into a *.h file, and the complete function code into a *.c file. But there is more to than that. I guess you have somehow compile the *.c file or something ???
I'm just not familiar with it at all. I'd like to do it with the SimpleIDE if it is possible.

I have translated some code to C and I have gotten everything to work by putting all the code in one file. But I'd like to make libraries for myself and others to use.

Bean

Rsadeika

A couple of months ago I asked that question, Steve mentioned, at that time, SIDE was not able to do that, creating lib files. I just looked at the latest SIDE, and did not see that function as being added, just yet. So, David will have to show us the alternative way too accomplish this.

Ray

jazzed

Hi Folks.

A C Library has two possible meanings.

1. a collection of functions in one or more source files
2. a binary archive of objects containing functions

SimpleIDE supports creating and using functions in one or more source files, but only allows using binary archives. It may be possible at some point to create a binary archive library in a a "simple" way in future release, but not at this time. I've posted an enhancement issue for this.


As to the first meaning, files can be added to a project either by copying them to the project folder or by linking to the files in a separate folder. Please see the Project Manager section of the user guide.

Best practices for creating C libraries that can be used in/with a binary archive:

1. A binary archive library is a collection of objects built from sources.
2. A library header file is used for compile-time function type checking for the library.
3. For every .c file there should be a .h file - a source module.
   • The .c file should contain the implementation of a single public function
   • The .h file should contain the public signature (and struct types if necessary)
4. Single .c modules should be as light weight as possible.
5. Linking with a function in an object will include the entire object.
6. A summary library .h file can include all the other .h files.
7. A library .c file should not include the summary .h file.

Hope this helps.
--Steve

David Betz

Steve gave an excellent summary of libraries. I just wanted to add that the command line tool for creating libraries is:

propeller-elf-ar

You can create a library from a number of object files by the following sequence of commands:

propeller-elf-gcc -Os -c -o file1.o file1.c
propeller-elf-gcc -Os -c -o file2.o file2.c
propeller-elf-gcc -Os -c -o file3.o file3.c
propeller-elf-gcc -Os -c -o file4.o file4.c
propeller-elf-ar rs libmine.a file1.o file2.o file3.o file4.o

This will create a library called libmine.a which you can include in your program using the propeller-elf-gcc command line option "-lmine".

ersmith

David and Steve have addressed the issue of binary libraries. These have the advantage that only the functions you actually use will be included in the output. However, for many purposes a source code library will work fine, and it will avoid the complication have having to have different binary libraries for different memory models (XMM, LMM, etc.).

The easiest way to create a source code library is to put all the functions for that particular library into one .c file (this is exactly the opposite of best practice for binary files, but makes managing the source code easier). Put declarations for all the functions or variables that you want users to be able to access into a .h file. Let's assume your library is called "foo", so it has foo.c and foo.h. To use the library in a project called "blah" put

#include "foo.h"

into your main source code file blah.c, and add foo.c and foo.h to the project. Steve's user guide discusses how to do this:

To add new files to the project, right click on the main program filename (or another if listed). When you add a file to the project, it must already exist somewhere on your computer. You can make a new file in the editor and save-as for example. If you choose a file outside of the project directory, the file will be copied to the directory. File names are added in alphabetical order except the main project file.