Libraries
From NetBurner Wiki
Contents |
[edit] Why Use Libraries?
Don't Repeat Yourself (DRY) is a basic principle of computer science. Libraries of reusable code are one major way to achieve that goal on the NetBurner platform. Writing code for a library is in theory no different than writing code for the NetBurner itself. In fact the code compile cycle will be faster because compiling a library requires fewer steps (building the web pages and running the compression tools can be skipped). In reality writing a good library takes longer because to achieve maximum code reuse, will require more careful planning, more testing and most likely several rounds of refactoring. Libraries also have the benefit of only linking in the code you use. If you are developing more than one project and not using libraries chances are good you're starting with an existing project and quite likely including code you don't need. If not, you're being careful to go through and delete everything you don't need, using a library will relieve you of this work. If you leave your libraries in your workspace, they are no harder to work with than code embedded directly into the main device project.
[edit] Getting Started Creating a NetBurner Device Library
If you're running a full version of Eclipse with CDT (as opposed to NBEclipse bundled with the NNDK) you'll see options for Static and Linked libraries. For the NetBurner those libraries are not relevant. We are only interested in creating NetBurner Device Libraries from the File->New->C++ Project dialog. After creating a library you'll immediately want to check the project properties. In particular you want to look at your C++ include paths and make sure that any required paths you might need will be there. In the full version of Eclipse no default paths are added so you need to add them. Once you do that you just start add your classes, fill them up with code and compile.
You'll also notice the the properties dialog for a project is noticeably shorter than for a NetBurner device. There are no sections for CompHtml, the Linker or for Objcopy.
[edit] Accessing the header files
Using your library means you must have access to your header files. You can do this via the workspace or via the filesystem. While you're developing your library you'll probably want to use the workspace. The same decision will be required when you set up the linker. You'll probably want to use the same method for both the header files and the linker. See the next section for images and more details.
[edit] Linking
There are two ways you can use your custom library in a NetBurner device project. You can link it via the Workspace or you can link it directly from the file system. While your library is being developed or fresh from being developed you'll probably find it more convenient to link it from the workspace. Once both your library and your project are final you may want to relink via the file system. See the section below on maintenance. The image shows an example of the steps you would take to use the workspace option to link your library. In this example the library being shown is already linked and you can see the final result being pointed to by the red arrow.
There are also options in the NetBurner for using references to projects as shown in the image below. You can experiment with this method of linking to a library but I've found using references causes too many gratuitous recompiles. Linking via the file system or workspace doesn't always recompile enough but I find that the preferable choice.
[edit] Forcing a Build
If you just change your library code and you're using Eclipse's managed make system your NetBurner device project won't automatically rebuild when when you hit rebuild. It won't think there is anything to do. Usually editing any .cpp file (even if you just add a space), rebuilding will be enough to get the modified library to link in. The project references feature described below should work. But on my system it causes significant heartache. I'm leaving the description in for how it's supposed to work and in case any brave soul out there wants to verify the behavior. If you get in trouble make to sure to read the blog article referenced above, it will save you lots of time restoring your libraries so they build properly again.
The easiest solution is to set your library as a project reference to your device project. Right click on your device project in the Project Explorer and select Properties.You should see a dialog similar to the one shown below:
Just check the libraries that your device project depends upon and now when you change your library your device project will detect the change and when you tell it to build it will relink.
You'll notice when you make a change in your device project that conflicts with your library, compiler error links will appear in your library. There really is nothing wrong with your library this is just the compiler trying to help you out and show you where the incompatibility lies. However, once you correct your project, the error icons can still appear on your library. Rebuilding the library will fix the icons. It's often a good idea to do clean builds on your library and your project. You could change something in your library that would break your project but you don't rebuild your project you won't know it. If you use a library across multiple projects it's not a bad idea to do a clean build on all of them when you change the library. It's a lot easier to find and fix problems right after you've made a change than two years later. If you are adding new functionality to a library this isn't as necessary and doing clean builds does take longer so I try to find a balance between quick turn around builds when needed, and avoiding unpleasant surprises for too long.
Using your own libraries is really no different than using the NetBurner built in libraries but at first it won't feel that way. That's because the NetBurner libraries have been tested and been in use for years and they seldom change. Your libraries on the other hand will probably be changing constantly as you add new functionality and refactor them. The benefits or using your own library will be apparent when you start that next project and you get to pick and choose the functionality from your library with laser like precision.
[edit] When Libraries Use Other Libraries
This is easy to overlook so pay attention. As you get comfortable with using libraries the day will come where you will write MySpecialLibrary. It will rely on MyStandardLibrary. You will include MyStandardLibrary.a and the include files for MyStandardLibrary in MySpecialLibrary. Life will be good and MySpecialLibrary will compile without a whimper. Then you will create a NetBurner Device Executable called MySpecialLibrary_test (or any program that uses MySpecialLibrary). In the setup for MySpecialLibrary_test you will of course include the library path and include paths for MySpecialLibrary. What you might forget to do is tell the Linker the library path to MyStandardLibrary. It's easy to think that MySpecialLibrary knows all about that path (and it does), but it doesn't include that library automatically for MySpecialLibrary_test. The build process will complain mightily but you might not understand what it is trying to tell you. It will show lots of errors on MySpecialLibrary. So you'll go rebuild MySpecialLibrary and the errors will all go away. Then you'll go back and rebuild MySpecialLibrary_test and they'all all show up again. When you see that behavior tell yourself you forgot to include a library in the Linker Libraries section.
[edit] Maintenance and your Source Code Control System
Depending on your coding habits (or your company policies) you may need or want to check your headers and compiled libraries into your source code control system along with your project. When you get to this stage it is time to switch to using the file system. Usually you'll create a lib and include folder at the same level as your src folder and you'll move all the libraries and library headers you use into these folders. Nothing would be more frustrating for a maintenance programmer than to check out your code to make a simple change only to find that the only library file is the current version that has several years of incompatible changes. Of course you'll have been checking the source code for your library in as well so that can always be retrieved, but be nice to the next programmer and make it easier on them. You'll be glad you did, especially if the next programmer is you.
