From ca7ed773f142af41c13889fc42cde91f5bdc0cbd Mon Sep 17 00:00:00 2001 From: mmdolze Date: Sat, 20 Nov 2010 16:45:22 +0000 Subject: [PATCH] Restructure chapters in the developer guide. Add chapter about programming and making releases. Add driver acceptance guideline. --- docs/lcdproc-dev/Makefile.am | 13 +- docs/lcdproc-dev/add-your-driver.docbook | 103 +++++- docs/lcdproc-dev/bookinfo.docbook | 13 +- docs/lcdproc-dev/lcdproc-dev.docbook | 5 +- docs/lcdproc-dev/make-driver.docbook | 21 -- docs/lcdproc-dev/programming.docbook | 436 +++++++++++++++++++++++ docs/lcdproc-dev/releasing.docbook | 299 ++++++++++++++++ docs/lcdproc-dev/shared-files.docbook | 2 + 8 files changed, 851 insertions(+), 41 deletions(-) create mode 100644 docs/lcdproc-dev/programming.docbook create mode 100644 docs/lcdproc-dev/releasing.docbook diff --git a/docs/lcdproc-dev/Makefile.am b/docs/lcdproc-dev/Makefile.am index 06fec2d..f67252b 100644 --- a/docs/lcdproc-dev/Makefile.am +++ b/docs/lcdproc-dev/Makefile.am @@ -1,15 +1,16 @@ ## Process this file with automake to produce Makefile.in -EXTRA_DIST = lcdproc-dev.docbook \ +EXTRA_DIST = add-your-driver.docbook \ bookinfo.docbook \ - introduction.docbook \ - shared-files.docbook \ - make-driver.docbook \ - add-your-driver.docbook \ driver-api.docbook \ + introduction.docbook \ language.docbook \ + lcdproc-dev.docbook \ license.docbook \ - README.docbook + make-driver.docbook \ + programming.docbook \ + README.docbook \ + shared-files.docbook ## convenience targets diff --git a/docs/lcdproc-dev/add-your-driver.docbook b/docs/lcdproc-dev/add-your-driver.docbook index 7e42af2..da82c1b 100644 --- a/docs/lcdproc-dev/add-your-driver.docbook +++ b/docs/lcdproc-dev/add-your-driver.docbook @@ -5,33 +5,105 @@ Introduction -LCDproc is meant to be modular, it is relatively easy to add new input and output drivers to LCDproc. +LCDproc is meant to be modular, it is relatively easy to add new input and +output drivers to LCDproc. -This chapter will explain you the major steps and few gotchas of adding your own driver to LCDproc. Enjoy! +This chapter will explain you the major steps and few gotchas of adding your +own driver to LCDproc. Enjoy! + + + +Be sure to read and +as well. + + +Rules for accepting new drivers + +LCDproc is open source software. Anyone is free to take LCDproc's code, write +his own driver and publish the modified sources somewhere again. If you want your +driver to be included in LCDproc's code some conditions have to be met: + + + + The hardware (display or enclosing product) is publicly sold + OR the schematics and firmware (if required) are publicy + available. + Therefore I will not commit drivers for displays ripped out + from an old telephone for your private hardware project and are not + available otherwise. + + + + The driver is released under (L)GPL and has an appropriate + copyright notice. + + + The submitter is or is acting on behalf of the original driver + developer. + I will not submit drivers found somewhere on the internet and + submitted without the original developer's acknowledgement. + + + + The driver describtion contains a valid email address for contacting + the submitter or developer. + + + The code is commented AND includes appropriate + Doxygen comments, especially for private / non-API functions. + + + End user documentation (updates to man pages AND + user-guide in docbook) is available. + + + Driver options are described in the end user documentation + AND LCDd.conf. + + + The driver adhere the style guide as described in . + + + + + + Autoconf, automake, and Everything! How I Learned to Stop Worrying and Love the Configure Script -It was decided pretty early in LCDproc's life to use GNU autoconf and GNU automake. This allows LCDproc to be ported to several platforms with much less effort. It can be quite daunting to understand how autoconf & automake interact with each others and with your code, but don't be discouraged. We have taken great care in making this as simple as possible for programers to add their own driver to LCDproc. Hopefully, you'll only have to modify two files, one for autoconf and one for automake. +It was decided pretty early in LCDproc's life to use GNU autoconf and GNU +automake. This allows LCDproc to be ported to several platforms with much +less effort. It can be quite daunting to understand how autoconf & +automake interact with each others and with your code, but don't be +discouraged. We have taken great care in making this as simple as possible +for programers to add their own driver to LCDproc. Hopefully, you'll only +have to modify two files, one for autoconf and one for automake. -The first thing you need to do is to find a name for your driver, it should be as descriptive as possible; most drivers are named after their respective chipset, for example hd44780, mtc_s16209x, sed1330 and stv5730, others are named after the company that makes that particular LCD display, for example CFontz and MtxOrb. Remember that these names are case sensitive. In this chapter, we'll use myDriver (which is an absolute non-descriptive name). +The first thing you need to do is to find a name for your driver, it should +be as descriptive as possible; most drivers are named after their respective +chipset, for example hd44780, mtc_s16209x, sed1330 and stv5730, others are +named after the company that makes that particular LCD display, for example +CFontz and MtxOrb. Remember that these names are case sensitive. In this +chapter, we'll use myDriver (which is an absolute non-descriptive name). Autoconf and its friend, acinclude.m4 -You need to add your driver to function LCD_DRIVERS_SELECT of file acinclude.m4. This can be done in three steps. +You need to add your driver to function LCD_DRIVERS_SELECT of file +acinclude.m4. This can be done in three steps. @@ -101,7 +173,10 @@ allDrivers=[bayrad,CFontz,CFontz633,...(big list)...,tyan,ula200,xosd, -If your driver only works in some platform or requires a particular library or header, you can add your autoconf test here. You can see how other drivers do it, but if you're not sure on how to do this, just send an email to the mailing list and we'll make it for you. +If your driver only works in some platform or requires a particular library +or header, you can add your autoconf test here. You can see how other drivers +do it, but if you're not sure on how to do this, just send an email to the +mailing list and we'll make it for you. @@ -111,12 +186,16 @@ If your driver only works in some platform or requires a particular library or h Automake and its friend, Makefile.am -Allready half of the job is done! Not to bad, wasn't it? The rest should be just as easy. In this section, you'll be adding your driver to the file server/drivers/Makefile.am. As you can guess, it's the Makefile for the drivers. This can be done in three (or two) simple steps. +Allready half of the job is done! Not to bad, wasn't it? The rest +should be just as easy. In this section, you'll be adding your driver to the +file server/drivers/Makefile.am. As you can guess, it's the Makefile for the +drivers. This can be done in three (or two) simple steps. Step 1 -First, you need to add your driver to the list of drivers in this file, this list is called EXTRA_PROGRAMS. +First, you need to add your driver to the list of drivers in this file, +this list is called EXTRA_PROGRAMS. This @@ -132,9 +211,13 @@ EXTRA_PROGRAMS = bayrad CFontz ...(big list)... ula200 xosd myDriver Step 2 -This second step is only needed if your driver needs a particular library. If it doesn't, you can skip to step 3. +This second step is only needed if your driver needs a particular +library. If it doesn't, you can skip to step 3. -You basically need to put you driver name followed by _LDADD and egal this to the name of the library that you need. Usually, these library are substituted by a autoconf variable, if you're not comfortable with this, you send an email to the mailing list and we'll set this up for you. +You basically need to put you driver name followed by _LDADD and egal +this to the name of the library that you need. Usually, these library are +substituted by a autoconf variable, if you're not comfortable with this, you +send an email to the mailing list and we'll set this up for you. For example, we would put this for our fictional driver diff --git a/docs/lcdproc-dev/bookinfo.docbook b/docs/lcdproc-dev/bookinfo.docbook index 8d9fabd..fdb5fa9 100644 --- a/docs/lcdproc-dev/bookinfo.docbook +++ b/docs/lcdproc-dev/bookinfo.docbook @@ -5,21 +5,24 @@ + +Markus +Dolze + + Peter Marschall -
peter@adpm.de
 Guillaume Filion -
gfk@logidac.com
 -2009-05-21 +2010-11-20 0.0.3 @@ -29,6 +32,10 @@ It covers LCDproc 0.5.x. Users should read the user guide. + +2010 +Markus Dolze + 2006 Peter Marschall diff --git a/docs/lcdproc-dev/lcdproc-dev.docbook b/docs/lcdproc-dev/lcdproc-dev.docbook index 02a95a2..bd5385a 100644 --- a/docs/lcdproc-dev/lcdproc-dev.docbook +++ b/docs/lcdproc-dev/lcdproc-dev.docbook @@ -3,11 +3,13 @@ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ + + ]> @@ -17,10 +19,11 @@ &introduction; &language; +&programming; &shared-files; &driver-api; &add-your-driver; -&make-driver; +&releasing; &license; diff --git a/docs/lcdproc-dev/make-driver.docbook b/docs/lcdproc-dev/make-driver.docbook index 2dea2d8..0b3fca1 100644 --- a/docs/lcdproc-dev/make-driver.docbook +++ b/docs/lcdproc-dev/make-driver.docbook @@ -1,22 +1,3 @@ - -Making a LCDproc driver - - -Introduction - - -LCDproc is meant to be modular, it is relatively easy to add new input and -output drivers to LCDproc. Actually, there are a few things that you can do -to make your life easier, they are listed here. - - - -This chapter will explain you the major steps and few gotchas of adding your -own driver to LCDproc. Enjoy! - - - - Shared files specific for drivers @@ -443,5 +424,3 @@ myDriver_SOURCES: lcd.h lcd_lib.h myDriver.c myDriver.h report.h adv_b - - diff --git a/docs/lcdproc-dev/programming.docbook b/docs/lcdproc-dev/programming.docbook new file mode 100644 index 0000000..77dcb59 --- /dev/null +++ b/docs/lcdproc-dev/programming.docbook @@ -0,0 +1,436 @@ + +Programming for LCDproc + + +Get the source + +If you want to start programming for LCDproc you will need the have +the most current source code available. You can get it several ways: + + + + Download yesterday's CVS version of as a tarball (prefered). + + + Download the latest version from CVS. + + + Download the last stable release from Sourceforge. (This is not + recommended as stable release may be months behind the current version.) + + + + + +Download Yesterday's CVS Version of LCDproc as a Tarball + + +There are nightly distributions of the CVS branches of LCDproc. You can +download them from . +For development we recommended to use the 'current' branch. + + + +To extract the files run + + + +$ tar xvfz lcdproc-CVS-current.tar.gz + + + + + +Download The Latest Version of LCDproc from CVS + + +Of course you can download the latest stuff from CVS via anonymous login. +For more information on how to use CVS see +About CVS +on Sourceforge. + + + +Login to CVS: + + + +$ cvs -d:pserver:anonymous@lcdproc.cvs.sourceforge.net:/cvsroot/lcdproc login + + + +(Hit enter when prompted for a password.) + + + +Get the files from CVS: + + + +$ cvs -d:pserver:anonymous@lcdproc.cvs.sourceforge.net:/cvsroot/lcdproc checkout -P lcdproc + + + +Once you've done that and want to update the downloaded files to the latest stuff +you can use the "update" command of CVS (make sure to be in the lcdproc directory!): + + + +$ cvs update -d + + + +Now that once you have downloaded the files you can prepare them for +compiling, but first you should (you don't have to) copy them to another +place on your machine. + + + + + + + + + +Code style guideline + + +LCDproc has been developed by many contributors over many years. You may find +different programming styles (naming, indention, etc) in the source code. + + +When modifying an existing file, please take a careful look at its style and +program continueing that style instead of mixing it up with another one even +if it does not comply with the guidelines written below. + + +For newly added files the following guideline describes how source code +should look like. + + + + All new submitted files will be passed through BSD indent + to enforce the style described below. + + + + +File format and indention + + + + Language: The programming language used for LCDd + (server core), drivers and the lcdproc client is C. + No other programming lanuage will be accepted. + + + + + File encoding: Files shall either encoded as UTF-8 or + ISO-8859-1 and line endings shall be Unix type. + + + + + Line length: Lines of source code should be wrapped + at column 80. + + + + + Indention: Tab indention shall be used (with tab + width set to 8 characters). Only exception are switch labels which are + indented a half tab (4 characters). + + + + + License: LCDproc is released under GNU General Public + License version 2 (GPL v2) and every file shall have a standard copyright + notice. + + + + + + +Naming conventions + + + + Function names: + Function names shall be lowercase. We do not use CamelCase. Multiple words + are separated by underscore. + + + + + Variable names: + We do not use Hungarian Notation. CamelCase may be used, + but names shall beginn with a lowercase letter. + + + + + Constants: + Constants shall be written in uppercase using underscore to + separate multiple words. + + + + + Names of constants, variables and functions + +/* Constants */ +#define KEYPAD_AUTOREPEAT_DELAY 500 +#define KEYPAD_AUTOREPEAT_FREQ 15 + +/* Variable names */ +MODULE_EXPORT char * api_version = API_VERSION; +MODULE_EXPORT int stay_in_foreground = 0; +MODULE_EXPORT int supports_multiple = 1; + +/* Function names */ +void HD44780_position(Driver *drvthis, int x, int y); +static void uPause(PrivateData *p, int usecs); +unsigned char HD44780_scankeypad(PrivateData *p); + + + + + +Comments + + + + All code comments shall be C-style comments (/* */). + Comments spanning multiple lines shall have a star at the beginning of + each line. + + + + + C++-style comments (//) may be used to comment out + single lines of code to disable these lines. Larger blocks of code which + shall be disabled should be wrapped within C-style + comments or using pre-processor directives (#if ... #endif). + + + C++-style comments shall not be used in general. + + + + + We use Doxygen to document our source code. Functions shall be documented + using Doxygen-style comments (/** *). + See Doxygen Manual + for more information and how to use it. + + + + + If you carefully formatted a comment, you may use the special comment + /*- */ (comment start is star minus) to prevent automatic + reformatting. This usually applies to the standard copyright notice. + + + Standard copyright notice + +/*- + * Copyright (C) 2010 Your Name <your_email_address> + * + * This file is released under the GNU General Public License. + * Refer to the COPYING file distributed with this package. + */ + + + + + + + +Statement style + + + Function declarations: + + Function declarations have their declaration and + opening brace split accross two lines. + + + Function names start in column one. The return type is placed on the + previous line. + + + There is no space between the function name and '('. + + + A function declaration + +/** + * This is a Doxygen function description. + * + * \param y The number of years + * \param str Pointer to a string containing X + * \return 0 on success; -1 on error + */ +int +this_is_a_function(int y, char *str) +{ + code +} + + + + + + Operators: + + There shall be a space characters before/after an operator or assignment, + except for increment (++) or decrement (--) + operators. + + + Space around operators + +if (p->dispSizes[dispID - 1] == 1 && p->width == 16) { + if (x >= 8) { + x -= 8; + relY = 1; + } +} + +x--; /* Convert 1-based coords to 0-based */ +y--; + + + + + + Function calls: + + There shall be no space between the function call and the opening '(' of + the parameter list. Within the parameter list a space shall be after each + parameter. + + + Function call + +lib_vbar_static(drvthis, x, y, len, promille, options, p->cellheight, 0); + + + + + + Compound statements: + + Opening braces occur on the same line as the + statement. + + + Else statements: Else statements are placed on a line of their own, even + is there is a previous closing brace. + + + Opening and closing braces may be ommited on single line compound + statements. However, if one part of an if-else-statement requires braces + the other part shall have braces as well. + + + If-else with braces + +if (...) { + code +} +else { + code +} + + + + If-else with single statements + +if (...) + print(); +else + err = 1; + + + + Other compound statements + +while (...) { + code +} + +for (a = 0; a < max; a++) { + code +} + +/* case labels are indented one half tab stop (4 spaces) */ +switch (icon) { + case ICON_BLOCK_FILLED: + HD44780_set_char(drvthis, 6, block_filled); + break; + case ICON_HEART_FILLED: + HD44780_set_char(drvthis, 0, heart_filled); + break; + case ICON_HEART_OPEN: + HD44780_set_char(drvthis, 0, heart_open); + break; + default: + return -1; /* Let the core do other icons */ +} + + + + + + + + + + + + +Submitting code + +When you have finished modifying the code you may decide to submit it to +the LCDproc project. You usually do this by submitting a patch for review to the +mailing list. + +To create a patch you need the unmodified files and the files containing +your modificatiosn. Usually you do this by storing an unmodified copy of the +sources in one directory and another copy with your modifications in another +one. You then run diff like this: + +diff + + + +> mymodifications.patch + + +Please use unified diff format ( option) only! +When running diff using +is strongly recommended. The file diff_ignore contains an +exclusion list which makes cvs ignore all generated files +(Makefiles, log files, object files, etc.) + + +If you have modified files in a source tree you checked out from CVS +you can also run cvs diff from the working directory: + +cvs diff +> mymodifications.patch + + +Some versions of cvs diff will not handle new files +because these are unkown to the repository. There are ways to make cvs believe +the files existed previously (fake add) but this is not recommended. You will +need to submit new files 'as-is' in this case. + + + + + diff --git a/docs/lcdproc-dev/releasing.docbook b/docs/lcdproc-dev/releasing.docbook new file mode 100644 index 0000000..31abcec --- /dev/null +++ b/docs/lcdproc-dev/releasing.docbook @@ -0,0 +1,299 @@ + +Making a release + + +This chapter describes the steps necessary to create a software release of +LCDproc. It is intended to guide the release manager when creating a new +release. + + + +Creating a source code release + +Steps to create a new software release of LCDproc + + + Update year of release in HEAD. The following files need to be updated: + + server/main.c + clients/lcdproc/main.c + docs/lcdproc-user/bookinfo.docbook + docs/lcdproc-dev/bookinfo.docbook + + + + + + + Make a backup of the CVS repository to the local disk. This is needed if + something goes wrong. Run: + rsync -av 'lcdproc.cvs.sourceforge.net::cvsroot/lcdproc/*' . + + + + + + Check out the CVS stable release branch. Run: + + cvs -d:ext:<your_sf_userid>@lcdproc.cvs.sourceforge.net:/cvsroot/lcdproc checkout -r stable-0-5-x -d lcdproc-0-5-x lcdproc + and change into the stable-0-5-x directory. + + + + + + Merge HEAD to stable. This step is only required if the release + will be done from HEAD. + + + + + Run: + cvs -q update -j stable-0-5-x -j HEAD + + + + + + Revert files that need to retain their version number after merge. Due to + some wired import of external files, some files always get their $Id$ tag + updated, even if there has been no change. The following files should be + reverted to their previous version (given that there has really no change + happened): + + clients/examples/lcdident.pl + clients/metar/lcdmetar.pl + contrib/interface-demo2/interface.c + contrib/interface-demo2/nstrcmp.c + + Run cvs update -C on these files. + + + + + + Update version numbers for stable branch. See + for the list of affected files. + + + + + + Commit everything. Run: cvs commit -m "Sync with HEAD" + + + + + + + + + + Create a release branch in CVS. Run: + cvs tag -b lcdproc-0-5-A where + A is the version number of the next release. + + + Release branch names are all lowercase with hypens to separate + elements! + + + + + Now you have created a branch from which the new release will done. Before + continuing either checkout this new branch to a new workding directory + or update the current one by running: + cvs update -r lcdproc-0-5-A + + + + + + + + Update version numbers for release and commit the changes. See + for the list of affected files. + + + + + + Set a CVS tag for the release. Run: cvs tag LCDPROC_0_5_A_RELEASE + where A is the version number of the next release. + + + Release tag names are all uppercase with underscores to separate + elements! + + + + + + Export the release source tree as anonymous. This step is intended to check + if all files are correctly tagged with the new release in the source tree. + + + Run: cvs -d :pserver:anonymous@lcdproc.cvs.sourceforge.net:/cvsroot/lcdproc + -z3 export -r LCDPROC_0_5_A_RELEASE lcdproc + + + + + + Create the release tarball by running: + + + + sh autogen.sh + ./configure + make distcheck + + + + + + + Test the newly created release tarball at least once. Try to build and + install it with all drivers enabled. Better: Try to build and install with + several library options turned on and off. + + + + + + Create the release notes. The release notes should be an easy to read + summary of changes in this release. The ChangeLog + file is not very good as release notes as it is just a chronological + list of things that happen. + + + The release notes should talk about: + + Fingerprint (SHA-1) of the release tarball + Known bugs + New drivers + Other important changes within drivers, the server core and + clients + Everything else the user has to now for upgrading his + installed version + + grouped by topics of interest. + + + + + + Upload the new release and release notes to Sourceforge. + + + + + + Announce the new release. + + + Send notice about the new release to the LCDproc mailing list + (lcdproc@lists.omnipotent.net) and the lcdproc-announce + mailing list on Sourceforge (lcdproc-announce@lists.sourceforge.net). + Also mention the new release on the LCDproc website download and front page. + + + + + + + Files that need version numbers updated + BUGS + ChangeLog + configure.in + server/menuscreens.c + docs/lcdproc-dev/bookinfo.docbook + docs/lcdproc-dev/driver-api.docbook + docs/lcdproc-dev/introduction.docbook + docs/lcdproc-user/bookinfo.docbook + docs/lcdproc-user/how-to-obtain.docbook + + + + + +Creating a documentation release + + +Any release of LCDproc is accompanied the the user guide and developer guide. +Here is how to create these documentation packages. + + +Steps to create the documentation package + + + Get the release tarball and extract it (or change to the CVS directory + exported in and change to docs/lcdproc-user. + + + + + Create the documentation package by running: + xmlto -o lcdproc-0-5-A-user-html xhtml lcdproc-user.docbook + + + + + Create a tarfile of the documentation package: + tar -czf lcdproc-0-5-A-user-html.tar.gz + lcdproc-0-5-A-user-html + + + + + Repeat the above steps for the developers guide, replacing -user + with -dev where appropriate. + + + + + Upload the files to the Sourceforge file release system. + + + + + +The online documenation consists of the user and developer guide, each +converted to a single file for viewing online. + + +Steps to create the online documentation + + + Get the release tarball and extract it (or change to the CVS directory + exported exported in and change to docs/lcdproc-user. + + + + + Create the documentation file by running: + xmlto xhtml-nochunks lcdproc-user.docbook + + + + + Rename the file: mv lcdproc-user.html lcdproc-0-5-A-user.html + + + + + Repeat the above steps for the developers guide, replacing -user + with -dev where appropriate. + + + + Upload the files to our Sourceforge web site (not the file release system!) + and change htdocs/docs/index.html to point to the new + files. + + + + + + + diff --git a/docs/lcdproc-dev/shared-files.docbook b/docs/lcdproc-dev/shared-files.docbook index 1092c7b..5554f72 100644 --- a/docs/lcdproc-dev/shared-files.docbook +++ b/docs/lcdproc-dev/shared-files.docbook @@ -272,4 +272,6 @@ LL_MoveNode(list, amount); // Slides a node to another spot in the list +&make-driver; +