Contents:
XParam's license is GPL with an exemption. The exemption is that programs are not considered derivative works of XParam simply because they are linked in with the library. So, if that's all you're doing, the license simply does not apply to you, and you're free to do whatever you want. This is the case if you're a simple user of the library, a programmer of XParam-using programs, or even a registrator of new classes into XParam.
If, on the other hand, what you want to do is to add new features to XParam, fix an XParam bug, make XParam work better, or do any other activity that requires modification of the XParam source files (which includes the cpp files, header files, parser files, make files, project files, Perl scripts, etc., that come as part of the XParam distribution), then you are creating a derivative work of XParam, and that means that the XParam license binds you as though it was GPL. Chiefly, this means that you must make the new sources, with whatever changes you make, freely available under a license that is at least as restrictive as the XParam license. (Both GPL and LGPL fall under this category.) You must note the fact that these are not the original sources, that you are the one to change them, and where the original, unmodified sources can be found.
The simplest way to do all this is to mail us the relevant patch file (or its equivalent), and we'll do the rest. This can be done through our SourceForge homepage.
We chose the XParam license after reviewing many alternative licenses and finding them too restrictive. We wanted a license that would allow everybody to use the library. We thank Richard Stallman for pointing us to GNU's GUILE, that uses an analogous license.
What you want to do with a source distribution is follow the instructions given in the "Installing XParam" section of this manual. They will tell you exactly how to get from the sources to the binaries you want. You will, however, need to have some basic tools, such as a C++ compiler, installed.
Starting version 1.21, XParam also comes with an RPM, so it is no longer necessary to compile it on your computer. In the future, we hope that more and more packages will make use of this RPM, utilizing XParam as an I/O platform for their own packages. We know of some such packages that are currently being developed.
If you get a linker error, complaining that XParam does not find these two template functions, what your problem is likely to be, is that you forgot to link some files in with your project. Typically, you forgot to link in the files that register class T.
And, no. We didn't forget to include "xpv_facade_imp.h". The program is supposed to compile, link and run perfectly without this inclusion. If you try to put it in manually, you will only be making things worse. The omission of this header file is a well know trick, meant to speed up compilation. This is only supposed to cause you trouble if your C++ compiler is extremely old, in which case it will no doubt also lack several other features needed by XParam.
One possible cause for this problem is that you have two different versions of XParam on your computer, and are linking against a different copy of the library than you intend. For example, you may have downloaded a local copy of version 1.22, but are still linking against your RPM of version 1.21. Use explicit link and include paths to make sure you are compiling and linking with the intended copy of the library.
If you've checked these possibilities already, and the problem seems to be elsewhere, try compiling with -DXPARAM_STATIC_LIBRARY, and if that doesn't work either, look at the file xp_config.h, and see if there are other configuration options that may be applicable in your case.
If the problem persists, tell us about it. Also contact us if you found out that your compiler needs certain special tweaks to make XParam run on it. If we can make these tweaks become part of the package, we'll probably do so for the next release.
If you neglect to surround XParam's calls in a "try" block, you can very easily find yourself with an unhandled exception. Many polite compilers exit from the program in such a case, notifying the user of an unhandled exception. Other, less polite compilers simply make your program crash on a segmentation fault.
One of the features we want to add to XParam is a work mode in which XParam errors will be reported by means other than exceptions. (For example, you may want XParam to report errors on the standard error stream, and exit from your program immediately afterwards.) However, this is not currently supported, and we can make no guarantees nor even time estimates regarding when such a feature may be introduced.
If you've successfully registered simple cases of all of the above, there's no reason you shouldn't be able to register the whole thing together. If, on the other hand, this is the first time you've ever tried using XParam's registration, we suggest you start with a few less ambitious experiments.
If you feel that you've tinkered with XParam long enough to know that what you're trying should work and doesn't, do contact us and we'll try to help.
Here's one tip: XParam's registrations may take considerable amounts of heap memory to compile. If you've got many registration calls you need to make, do your compiler a favor and split them into several files.
Of course, that's just the list of environments that we managed to test in-house. Our install base likely spans many other environments as well, and we've only received relatively few reports about environments where XParam doesn't behave well.
One thing we've learnt about the C++ language is that no two compilers share identical views about it, nor are there two operating systems completely identical in their quirks. Generally speaking, when you port XParam to a new environment, it may take a little tweaking to make it run exactly right. (It is, after all, a very compiler intensive library.) However, on the whole, little to no tweaking is all it generally takes. It never posed any serious problems. Not even when we ported it originally from Linux to Windows.
The XParam distribution comes with an elaborate autoconf script, meant to work around the most common porting pitfalls, and we are using libtool as a further means of making the transitions easier, but neither of these systems is perfect.
If your operating system is not listed above, this is no reason to assume it won't work there. Try it. If it works, let us know. If it doesn't, let us know, too. If it originally didn't work, and you found a way to work around the problem, this is doubly true.
As a general policy, we haven't written in XParam any piece of code for which we have no means of testing. We know, for example, that XParam's dynamic loading mechanism will probably not work well on a Digital Alpha, because it was designed for a 32bit operating system. We could have written the code, but had no way of verifying that it actually works correctly. In all such cases, we rely on you, the XParam developer, to help us make XParam work on your favorite platform.
If you must have the documentation in HTML form, you can always produce it from the SGML. If you have SGML-Tools installed, the command
sgml2html --split=0 xparam.sgml
will yield documentation in a single HTML file.
If linuxdoc converters are not available to you, you can also find all of XParam's documentation, in formats ranging from single-file HTMLs, through PostScript, to PDFs, in the "XParam-docs" tar file, available for download from our SourceForge homepage.
If you're just interested in getting a general glimpse of what's planned in XParam's near future, you can take a look at the "help XParam" page on our homepage and at the "TODO" file in the distribution. We don't feel ourselves tied to either list, though, so don't be surprised if items not on either list supercede other, longstanding items.
If you want to help us, you can simply program any of the items on the "help XParam" list (it's very diverse in the skills it requires). Better yet, you can contact us and we'll figure out together what subproject best suits your capabilities.
In fact, if you'll just program for youself the features that you most need for XParam, and then send them to us, that will be great. Most of the features XParam has today were programmed because we needed them in our projects.
Next: Appendix: Conversion Rules
Previous: Usage Examples
Up: Table of Contents