Guidelines for new components

Index of this document:

This documentation contains guidelines for the organization of your wxCode component. While reading it you can see the structure of the 'template' folder described in the text here.

Remember that the format & the structure explained in this file will make your component not only standardized and thus easier to use in bigger projects but will also make possible to integrate it into the official wxWidgets distribution.

If you need further info/assistance with the structure of your component, please ask in the wxcode-users mailing list at wxcode-users@lists.sourceforge.net.


Source & header files

^ TOP

You should keep your sources in a "src" folder; they should all have a .cpp or .c extension (avoid .cxx or .c++ extensions); your include files should instead go into a "include/wx" folder so that they can be included as any other standard wxWidgets include file:

#include <wx/comp.h>

they should have a .h extension (avoid .hpp extensions).

To be able to support precompiled headers and also to be sure that your license applies to every piece of your code, you must always start your header and source files with some standard contents shown in wxCode/template/include/wx/mycomp.h and wxCode/template/src/mycomp.cpp.

Also, to support shared builds you should always include in your component the WXDLLIMPEXP_MYCOMP symbols in the declaration of each class, function, event... you should keep these defines in a separate include file (since they must be included in all the files of your project), look at wxCode/template/include/wx/mycompdef.h for a more detailed explanation about the things you need to support shared builds and also for an example of the declaration of WXDLLIMPEXP_MYCOMP macros.

Last, to support Unicode builds you should always enclose all the strings in your source code with the wxT() macro:

wxString str = wxT("hello world!");

for more info search in wxWidgets documentation.


Documentation

^ TOP

In order to make your component easily integrable in other applications, you need to provide a good documentation for it. Since you probably need to create a simple documentation and you want to do it quickly, I suggest to use doxygen (http://www.doxygen.org); it's a free program which creates the documentation of a project extracting the comments you put in your source and header files.

In this template component, you'll find a simple "Doxyfile" in docs/ folder. If you have already used the doxygen comment syntax in your component source files, then you probably need only to change the PROJECT_NAME field in the Doxyfile and then you can run doxygen to get your fresh docs!

› The ReadMe

Each component should provide at least a "ReadMe.txt" file in its root folder. Since all major info about the component are kept in the wxCode database, and you probably want to update your component's info only once when making a new release, such readme file should contain only the most important info; all other info should be updated in the wxCode website using the EDIT form.

For a simple template of the Readme of a component, see Readme.txt.template.

It's important to keep a "version" field in the readme so that the user who is already using your component can quickly find if he is using a version older than the version currently published in the wxCode website.


The build system

^ TOP

Even if it's not required that you use Bakefile as build system for your component you are strongly encouraged to do so because it's almost impossible to handle all build settings for all possible builds writing manually the makefiles or, even worse, editing the IDE project files: if you support ANSI/Unicode + static/shared + debug/release builds for your component's library and your component's sample you'll have up to 16 different configurations.

Also, consider that if users cannot build your component they will probably simply discard it and choose something else or they will just write their own versions... to make Open Source great you should make your code easy to compile. This also means that you should support many compilers (differently from Unixes, which usually have a standard GCC compiler, there are various win32 compilers: borland, watcom, digitalmars, msvc, mingw...).

Bakefile is very extensible and you can handle any required build option with it.
So, look at wxCode/build/bakefiles/ReadMe.txt for a quick-start guide on the generation (a matter of few minutes!) of the bakefile for your component.


The samples

^ TOP

Samples are:

In conclusion, you should always provide at least one sample per component. The easiest way to create a sample is to modify the "minimal" sample; look at wxCode/template/samples folder for the required file for a minimal sample.


The website

^ TOP

Your component's website should be stored in wxCode/components/YOURCOMP/website folder. This is necessary since the scripts of wxCode automatically search that folder (see section 5.2).

In order to create your component website you should:

  1. put in your component's website folder all the files you need to make the main page. You should *exclude* documentation and screenshots from that folder since they make CVS/SVN slower and wxCode provides other standard placed for these things (see below).
  2. edit your website/index.php file (open it in a simple editor and change it to suit your needs...).
  3. edit your website/image.png file: it should be a simple logo sized 160x120 px which gives an idea of the function of your component.
  4. upload your DOCUMENTATION to the wxCode website docs folder. You have to do this using some SFTP/SCP client (I use WinSCP on Windows - see www.winscp.net). Here is some detailed information to configure your client: SF SFTP service documentation page. Note that if the folder /home/project-web/wxcode/htdocs/docs/YOURCOMPNAME does not exists, then you should create it.
    Also note that you must use your private SSH key to log in to the webserver.
  5. using the same settings used for step #4, upload your SCREENSHOTS to the /home/project-web/wxcode/htdocs/screenshots/YOURCOMPNAME directory.
    Note that if the folder /home/projcet-web/wxcode/htdocs/screenshots/YOURCOMPNAME does not exists, then you should create it.

Note: Website write access is currently not automatically granted. Please ask a wxCode administrator to grant write access rights to you.

› About SVN-website synchronization

Automatically synchronizing the wxCode website is not supported by SourceForge anymore. wxCode has to be synchronized manually with the SVN version. That will be done by one of the wxCode administrators in irregular intervals. Also all component's "website" folders are updated on the server. So, all the files you put in YOURCOMP/website folder should be under SVN control and will be used to keep your component website up to date.


Other docs for wxCode

^ TOP

This ReadMe focuses on the *structure* that your component should follow. For hints about the design of your wxWidgets-based code at wxCode there are other documents at:

http://wxcode.sourceforge.net/faq.php

For help on SVN operations and SourceForge file release system, look at:

http://wxcode.sourceforge.net/maintguide.php

If you still need help then just ask on the wxcode-users mailing list.