From XastirWiki
Jump to: navigation, search

In April and May, 2019, the group voted to switch to Allman style code formatting. We were previously using BSD KNF style. We're now using 2-space indents, vertical brace alignment, and will always use braces even when optional (these were all part of the vote).

The command we used to reformat all of the codebase was:

    astyle -A1 -s2 -S -xW -j -z2 *.h,*.c

in each directory containing code. The equivalent to add to a .vimrc should be:

    " Using 'Artistic Style'or 'astyle' to autoformat/autoindent.
    " In VIM type 'gg' to go to the top of the file, then 'gqG' to reformat the code.
    " See http://astyle.sourceforge.net/astyle.html for details on the options.
    " Long options:
    " --style=allman (-A1)
    " --indent=spaces=2 (-s2)
    " --indent-switches (-S)
    " --indent-preproc-block (-xW)
    " --add-braces (-j)
    " --lineend=linux (-z2)
    autocmd BufNewFile,BufRead .c,.cpp,*.h set formatprg=astyle\ -A1\ -s2\ -S\ -xW\ -j\ -z2

however when this was tried some things got formatted differently yet. This may have been due to other settings in VIM that wrapped comments at different columns. Buyer beware.

Tabs

Set tabs to two characters, space filled. There should be no TAB characters appearing in the sources. For VIM, insert these lines into your ~/.vimrc file:

    :syntax on
    :set tabstop=2
    :set expandtab

For emacs, you should be able to use something like:

    (setq c-basic-indent 2)
    (setq tab-width 2)
    (c-set-offset 'substatement-open 0)
    (c-set-offset 'case-label '+)
    (setq indent-tabs-mode nil) 

Note that ".vimrc" files have been added to the Xastir and Xastir-Qt projects on Github, in every directory. Read that file for how to enable these directory-specific .vimrc files for a particular user.

For Emacs a project-specific config file was added to the top level of the Xastir and Xastir-Qt projects: ".dir-locals.el". Unfortunately, this mechanism can only set directory local variables, and cannot run specific emacs macros at a directory-local level. Therefore, the two "c-set-offset" lines still have to be done in your emacs startup file. The first makes sure the opening brace of a block is not indented, and the second assures that case labels are indented (emacs doesn't indent them by default, and would have them line up with the braces around a block instead).

Indentation

Indentation should be two spaces.

Braces

Bracing should be to the Allman standard (vertically aligned below the first character of the statement). Optional braces should ALWAYS be included.

    if ()
    {
        ....
    }
    else
    {
        ....
    }

Blank Lines

Put five blank lines between functions. This is to more easily see where each function begins.

Bug-fixes

Submit each bugfix or new feature as a separate patch. This makes testing and debugging of the patches easier. Use "git diff -w -r HEAD -u" to create the patch file instead of "git diff -u". This will compare your new version to the latest Git version, instead of the Git version that you originally checked out. Someone may have changed the version in the Git repository since you checked out the file. Make sure you're not removing somebody elses patches (that they've committed to Git recently) unless that's what you intended to do.

Snprintf()

Don't use the "snprintf()" function. Use "xastir_snprintf()" instead.

Patches

Patches: Use "diff -c" or "diff -u"

CFLAGS

CFLAGS for more debugging:

    -O2 -Wall -Wpointer-arith -Wstrict-prototypes -W -pedantic

Autoconf and Friends

The "bootstrap.sh" in the top level of the Xastir source tree must be run whenever building Xastir from a new git clone. This script creates configure and all the Makefile.in files it needs, by running aclocal, autoheader, autoconf and automake.

If acinclude.m4, configure.ac, or any Makefile.am has been changed you must rebuild 'configure' by rerunning the "bootstrap.sh" script.

Bumping Version Number

To bump the version number, change AC_INIT in configure.ac and then run bootstrap.

Building Source and Binary RPM's

NOTE: The Xastir project hasn't built source or binary RPMs in ages, and the instructions here may be completely wrong now.

Building source and binary RPM's. The example system in this case is SuSE Linux:

Check the xastir.spec.in file to make sure that all of the parameters at the top are correct. In particular check and update the "Release" and "Packager" lines. Release should be incremented by one for each new RPM with the same type of naming.

    ./bootstrap.sh
    mkdir -p build
    cd build
    ../configure
    make dist
    cp xastir-1.3.0.tar.gz /usr/src/packages/SOURCES/.
    su     /* must run rpm as root */
    cd /usr/src/packages/SOURCES
    tar xzf xastir-1.3.0.tar.gz
    rpmbuild  -bb  --clean  xastir-1.3.0/xastir.spec  /* Build binary RPM */
    rpmbuild  -bs  --clean  xastir-1.3.0/xastir.spec  /* Build source RPM */
    rpmbuild  -ba  --clean  xastir-1.3.0/xastir.spec  /* Build both RPM's */

These go through the entire build process, including configure and make, and clean up the cruft that would have been left in the /usr/src/packages/BUILD/ and /var/tmp/ directories.

When it's all done, the RPM's will be in:

/usr/src/packages/SRPMS/xastir-1.3.0-1.src.rpm

and/or

/usr/src/packages/RPMS/i386/xastir-1.3.0-1.i586.rpm

    rm -rf /usr/src/packages/SOURCES/xastir-1.3.0/
    rm /usr/src/packages/SOURCES/xastir-1.3.0.tar.gz

Release the new RPM files.

The new method is to run "BUILDRPMS" (and "LSB-BUILD" to create the LSB binary).

Language Files

If adding lines to one of the config/language* files, please add the same line to the other language files in English. Translators will eventually translate the English lines to the native languages.

Doing a Release

See the file "README.developers.md" in the Xastir source tree for details on what to do to create a release.

Send e-mail notices to:

,----Development Release Notices
| ,--Full Release Notices
| |
* * xastir at xastir.org
* * nwaprssig at googlegroups.com
* * aprssig at tapr.org
* * aprsnews at tapr.org
* * macaprs at yahoogroups.com
* * aprs at yahoogroups.com
  * SAR_APRS at yahoogroups.com
  * CSAR at yahoogroups.com
  * aprs at mailman.qth.net
  * linux-hams at vger.kernel.org (NO HTML!!!)
  * linux at tapr.org

This list is likely excessive and should be pared down.