This is the top level directory for the open source parts of LCDHost. It contains everything needed to build LCDHost plugins, with some extra attention to doing it using Qt. By default, simply opening the lcdhost.pro file in Qt Creator should let you build unsigned versions all of the plugins. Some plugins may not build on all platforms, or build but provide only limited features. ********************************************************************* *** Do I really need all this stuff? ********************************************************************* The reasonable minimum to get if you use the Qt SDK is the "lcdhost.pro" file and the "linkdata" subdirectory. The Qt SDK may be found at http://qt.nokia.com/products/qt-sdk ********************************************************************* *** What NOT to change ********************************************************************* Do *NOT* commit files at the top level, such as altering or removing existing files or adding new ones. The top level directory should only contain this "README", "lcdhost.pro" and ".hgignore". You may of course add any *un*versioned files anywhere. Just be very careful not to add them to the repository by mistake. If you want to add your own plugin subdirectory to the repository, that's fine as long as it compiles cleanly on both OS/X and Windows. If you can't test on either of those, see LH_LCoreReboot.pro for an example on how to limit a plugin to a single architecture. Do *NOT* commit to the project members private directories. Create a issue on the issue tracker about any bugs or problems that they need to adress, and label the issue appropriately. http://code.google.com/p/lcdhost/issues/list The private directories and their maintainers are: linkdata/ - maintained by Johan Lindh <johan@linkdata.se> codeleap/ - maintained by Andy Bridges <andy@bridgesuk.com> ********************************************************************* *** Keeping your code inside the repository ********************************************************************* It's fine to keep your code in a subdirectory of the repository root. In fact, it simplifies things a lot. Just read the "What NOT to change" bit above again. If you prefer to keep your source code closed, you can do that too while still keeping it inside the repository root. Just don't add it to the LCDHost repository. ********************************************************************* *** Configuring your build preferences ********************************************************************* You should create a file named "lcdhost.prf" in the top level repository directory. This is fine as it's both in ".hgignore" and you're not going to add it to the repository. This file will be included by "lcdhost.pro" to set the LH_PLUGINS_LIST variable that decides which plugins to build. It will also be included by the plugin project files, so you should configure any extra build steps there as well. If lcdhost.prf does not exist, lcdhost.pro will create a default one for you. Sample contents to build and sign a single plugin on Windows, assuming that the private key file is at c:/Users/UserName/private.pem and the public key can be downloaded from http://my.website/public.pem: LH_PLUGINS_LIST = MyPlugin CONFIG(debug): LH_DESTDIR=$$PWD/debug else: LH_DESTDIR=$$PWD/release SIGNATURE_PRIVATE_FILE = c:/Users/UserName/private.pem SIGNATURE_PUBLIC_URL = http://my.website/public.pem load($$PWD/linkdata/linkdata.prf) include($$PWD/linkdata/SignPlugin.pri) ********************************************************************* *** Building inside the repository ********************************************************************* While possible, it tends to clutter up the filesystem and the output of "hg status". The former is traditionally handled using build targets named "clean", "mrproper" and other silly things. The latter is usually handled by putting more and more glob's into ".hgignore". Personally, I prefer to use Qt Creator's "Shadow Build" option, which leaves the repository alone while building. ********************************************************************* *** How to build a LCDHost plugin with Qt Creator ********************************************************************* * This section is a work in progress. * You should already have cloned the repository so you can work on it. See http://code.google.com/p/lcdhost/source/checkout if you need help. By custom, and to trivially identify them as probable LCDHost plugins, we start all plugin projects with 'LH_'. So, assuming you want to call your plugin 'MyLCDHostPlugin', we'll call the project LH_MyLCDHostPlugin. *** Creating a skeleton C++ shared library with Qt Creator We'll create a skeleton C++ shared library project with our chosen project name. We'll assume that is "LH_MyLCDHostPlugin" here. In Qt Creator, select the menu item File -> New file or Project. In the "New" dialog, choose the Project template "Other Project" from the upper left list. Then select "C++ Library" from the right hand list. Click "Choose". The "C++ Library" dialog prompts for the type of library, it's name and it's location. Select "Shared Library", enter "LH_MyLCDHostPlugin" for the name. For "Create in", select the directory where this file and the lcdhost.pro file is. Don't worry, this is under source control, so even if you mess up you can clean up afterwards. Click "Next". You now get a "Target setup" dialog. Not much to do here. You may want to have "Use Shadow Building" checked, or Qt will clutter up the repository filesystem with it's generated Makefiles and other intermediate files. Make sure "Desktop" is checked. Let it create build configurations as it's suggesting. Click "Next". You now get to "Select Required Modules". For all LCDHost plugins written with Qt, you'll need QtCore and QtGui. QtCore is already checked for you. Check QtGui. Anything else requires you to know what the respective Qt modules do, so leave them unchecked unless you're a Qt professional. WARNING: Do *NOT* include QtWebKit. It's not suitable for use in a threaded environment. If you need render webpages, you should be using LH_WebKit. When done, click "Next". The new dialog allows you to confirm and make last adjustments to class and file names. Click "Next". The "Project Management" dialog may be your first indication that you're working within a mercurial repository. Here, you'll need to change the "Add to project" box so it reads "None". (Unless you're a committer on the project, but then, why are you reading this?). Then click "Finish". You now have a skeleton project capable of building a multiplatform generic shared library. It doesn't do anything, and isn't recognized by LCDHost as a possible plugin, but it's a start, and all you've had to do is click some buttons! *** Configuring your build This step is optional, but you might as well read it, or you'll get confused if you accidentally build using lcdhost.pro. Usually, you don't want to build all the plugins. It takes a long time, and you very likely already have them. Therefore lcdhost.pro looks for a file called "lcdhost.prf". It expects it to define a variable called "LH_PLUGINS_LIST", which is a list of the plugins that should be built, in order. In the directory with lcdhost.pro, create a text file named "lcdhost.prf" containing the text LH_PLUGINS_LIST = LH_MyLCDHostPlugin load($$PWD/linkdata/PluginsBase.prf) *** Creating a LH_QtPlugin descendant with Qt Creator Now you need to add in the LCDHost bits. First, add this line to your LH_MyLCDHostPlugin.pro file, after the "DEFINES += LH_MYLCDHOSTPLUGIN_LIBRARY" line but before "SOURCES += LH_MyLCDHostPlugin.cpp" load(../../lcdhost.prf) This tells qmake to first try including the lcdhost.prf file we just made. This should pull in the basic header files, include paths, sources and libraries needed to build a LCDHost plugin. Next you need to create a C++ class that inherits from LH_QtPlugin. So let's do that. In Qt Creator, select the menu item File -> New file or Project. From the lower left list "Files and Classes", select "C++". In the right hand list, select "C++ Class". Click "Choose...". For the class name, you can pick anything you like, but other plugins usually follow the convention "LH_QtPlugin_MyLCDHostPlugin". For "Base class", enter LH_QtPlugin. For "Type information", select "Inherits QObject". Examine the generated values for "Header file", "Source file". Change them if you prefer a different naming scheme (upper/lowercase etc). Closely examine the value for "Path". Qt Creator sometimes get confused about where to put things, but it should point to the newly created "LH_MyLCDHostPlugin" subdirectory under the checked out repository root. Click "Next". The "Project Management" dialog is here again! This time though, it should be spot on. We want "Add to project" to read "LH_MyLCDHostPlugin.pro" and "Add to version control" to be whichever VCS you're using, probably "Mercurial" if you checked out with hg. Make a final check on the file names and where they're going to be created, and then click "Finish". Next, we need to modify the newly created header so it includes the base class. Add the line #include "LH_QtPlugin.h" before the line class LH_QtPlugin_MyLCDHostPlugin : public LH_QtPlugin At this point the code should compile. It won't be recognized by LCDHost as a valid plugin yet - there's a bit more to that. *** Adding the LCDHost plugin specific bits Next we need to add the embedded XML document that identifies this as a LCDHost plugin, and create the required shared library exports so that LCDHost will be able to to load it as a plugin. There's a simple macro for all this. The macro goes into the implementation file, NOT the header file. So add this text to the end of LH_QtPlugin_MyLCDHostPlugin.cpp: LH_PLUGIN(LH_QtPlugin_MyLCDHostPlugin) = "<?xml version=\"1.0\"?>" "<lcdhostplugin>" "<id>MyLCDHostPlugin</id>" "<rev>" STRINGIZE(REVISION) "</rev>" "<api>" STRINGIZE(LH_API_MAJOR) "." STRINGIZE(LH_API_MINOR) "</api>" "<ver>" "r" STRINGIZE(REVISION) "</ver>" "<versionurl></versionurl>" "<author>My Name</author>" "<homepageurl>http://my.home.page</homepageurl>" "<logourl></logourl>" "<shortdesc>" "What my plugin does" "</shortdesc>" "<longdesc>" "Detailed instructions and help" "</longdesc>" "</lcdhostplugin>"; This has three effects. First, it creates an blank signature area that you can later fill in with SignPlugin if you choose. (You can automate this procedure, see linkdata/SignPlugin.pri). While a plugin is valid without having a signature area, it is strongly recommended to have one. The second thing it does is define and export the plugin class so Qt can load it. Third, it embeds the required XML document into the plugin. Without that, LCDHost won't recognize it as a valid plugin. That's it. You now have a bare bones LCDHost plugin. LCDHost will recognize it and load/unload it. It doesn't actually provide any features, but that's for another README. *** Further reading For Qt C++ plugins, examine LH_Text. For pure C plugins, examine LH_Image.