Imagine you have created an interesting application. Along the way, you discovered that your code needed to repeat a number of certain tasks frequently, so you put those tasks into functions. Now those functions are easy to re-use, and your code is tidy — great job!
But what if you want to use those handy functions in your next interesting application? You could copy and paste them from one applciation to another every time you want to use them. But there's a better way: create a simple library for them. Then, you can include that library in the beginning of any future program, and call any function in that library in much the same way you’ve been calling pause, high, low, and other functions from the simpletools library.
Make sure you have at least gone through the Propeller C – Start Simple [1] and Propeller C – Functions [2] tutorials before continuing here.
Start with some working code that has functions you might want to reuse. Here we have a very simple application with two functions to append whomever’s name you have printed with “is awesome!\n” or “ is epic!\n”.
/* Awesome Messages.c */ #include "simpletools.h" // Include simple tools void awesome(void); // Forward declarations void epic(void); int main() // main function { print("Nick"); // Print a name awesome(); // Append with "is awesome!\n" print("Jessica"); // Print another name epic(); // Append with "is epic!\n" } void awesome(void) // awesome function { print(" is awesome!\n"); } void epic(void) // epic function { print(" is epic!\n"); }
Before moving the awesome and epic functions to libraries, let’s test this code to make sure it works.
Alright, so we have working code with two functions that are destined for a simple library. After creating an awesome library, you won’t have to keep the forward declarations and functions in your code any more. They’ll be neatly tucked away in the awesome library, and all that you'll have to do in order to access them will be to add #include “awesome.h” to the beginning of your code.
The first step to creating a library named awesome is to save your application as libawesome inside a folder named libawesome. This folder has to be located in the Simple Libraries folder for SimpleIDE to access it, and to keep things neat we’ll place it all in a subfolder named My Libraries.
This should create a libawesome project.side project file and libawesome.c soure inside the libawesome folder. Both files must be there in the right place for creating the simple library. This is an important step, so let’s double-check that before moving on.
A simple library needs a header file. Recall from the Reusable Code Functions tutorial [3] that each function you created needed a forward declaration of its function prototype, to let the C compiler know what it might encounter. A library's header file collects these function prototypes in once place, so you don't have to add a forward declaration when using a function from the library. If a library uses functions from other libraries, its header file should also #include those other libraries.
So, let's make a .h file for your awesome library.
Now you have two files open in SimpleIDE: libawesome.c and awesome.h
Why #include simpletools.h?
The awesome and epic functions both use the print function. The print function is part of the simpletools library, so we need to #include it in the awesome library.
Simple libraries tend to have one or more C language source files. This is where the complete function definitions and their code blocks go. This file also has to #include awesome.h.
Now that the library has its header file with forward declarations and its source file with functions, the libawesome application doesn’t need them. The libawesome application is still important though. You will use it to build your library's output, and to test the functions to make sure they work as expected. The library's application file is sometimes called a test harness.
When your applications call the simpletools library’s pause function, the compiler doesn’t actually get anything from the .c file. Instead, it goes looking for a file named libsimpletools.a. The .a is short for archive, and the file is a binary image of the compiled C language source code. These files can help reduce the size of your program code.
Let's make the archive for your awesome library.
The Project Manager windowpane that opens up should look like this:
Propeller GCC is designed to work with several different memory models. In the Propeller C Learning System tutorials [4], we’ve been sticking with CMM (compact memory model). We’ll start by compiling the library for that memory model first.
Using a different board? Look for it by name in the Board Type list. If it's not there, click Help and look up Board Types in the SimpleIDE User Guide.
The next step is important; we need to configure the project to generate the library archive files.
After you have configured the project settings to create a project library and selected the memory model, you’re ready to build the project and create a library archive for the compact memory model.
After you do this, there’ll be a file named libawesome.a inside a cmm subfolder.
You can compile your code for other memory models. Let’s try LMM (large memory model), which executes the code faster, but also takes more memory for the same program (compared to compact memory model).
Memory models are different ways to store and execute the program code on the Propeller microcontroller and connected memory devices. The CMM Main Ram Compact memory model used most often the Propeller C Tutorials puts all the program code into a 32 KB file that gets loaded into the Propeller chip's main RAM, either directly or from an EEPROM chip like the one on the Activity Board (original or WX version). Other memory models might use a very large EEPROM, Flash memory, or just the memory in a single cog.
For more information on this advanced topic, see the user guide (click Help and select SimpleIDE User Guide).
SimpleIDE will have to be restarted before it can become aware of this library for use by other projects. After that, it’s a good idea to test and make sure a different project can use it.
/* Test Awesome Library.c */ #include "simpletools.h" // Include simple tools #include "awesome.h" // Include awesome library int main() // main function { print("Ken"); // Print a name awesome(); // Append with "is awesome!\n" print("Stephanie"); // Print another name epic(); // Append with "is epic!\n" }
Links
[1] https://learn.parallax.com/propeller-c-start-simple
[2] https://learn.parallax.com/propeller-c-functions
[3] https://learn.parallax.com/propeller-c-functions/reusable-code-functions
[4] https://learn.parallax.com/propellerc