HTTPS SSH
AVR Geany Support
=================

The files in this bundle were designed to simplify developing AVR projects in
Linux with Geany. After installing this bundle, you will have:

* An independent Geany profile so your AVR work and settings are isolated
  from your other Geany work and settings.
* A convenient means for adding code-completion tags from AVR library headers.
* A convenient means to create new AVR project directories that are 
  pre-populated with a comprehensive makefile and main.c file.
* Menu items for the most commonly used make targets.
* Overridden definition for the default Compile, Build, and Execute
  (not finished) commands so they are appropriate for AVR development.

The bundle is developed and tested on Debian Wheezy with the AVR toolchain 
found in the repositories.

Requirements
------------
To use this bundle you will need to have installed:

* geany        : obviously
* zenity       : display graphical dialog boxes from shell scripts
* avr-libc     : standard C libraries for AVR development
* binutils-avr : assembler, linker, other utilities
* gcc-avr      : C, C++, and Ada compilers

If you wish to write the microcontroller memory, then you will need:

* avrdude      : programmer 

If you wish to run simulations and do debugging, then you will need:

* simulavr     : Atmel AVR simulator
* gdb-avr      : debugger for AVR
* ddd          : graphical debugger frontend

Note: ICE with avarice is not yet supported.

Configuration
-------------
Here are the things you will have to do once.

Put the 'avr-geany-support' directory where you found this README somewhere
convenient. You'll be leaving  it there long-term, so choose wisely. Then, 
create a new Geany profile by executing in the "avr-geany-support" directory:

    $ cp -R geany-avr/ ~/.config

Note: This will create a new Geany configuration directory at
    ~/.config/geany-avr. If you want to use another name for the new
    configuration directory, then you will have to tweak things yourself. 

Start a Geany instance using the newly created geany-avr profile:

    $ geany -c ~/.config/geany-avr 

and in the newly opened Geany instance, under "Build > Set Build Commands",
change  the working directories for the "New AVR Project" and 
"Open codetag generator script" items to the *absolute path* where you are 
keeping "avr-geany-support".

Create a list of tags to be used by the autocompleter, by selecting  "Build > 
"Open codetag generator script" and running the script with "Build > Execute". 
If you add  additional libraries in the future, edit this script as documented 
in  the file and re-run it. Note that the tags produced by this script will 
apply to the entire profile, not just the project.

To simplify opening Geany with the AVR profile, you may wish to create a script
named 'geany-avr' somewhere in your PATH along the lines of:

    #!/bin/bash
    geany -c ~/.config/geany-avr $@ &

Ongoing use
-----------
Here are the things you will probably do more than once.

To launch Geany with the geany-avr profile you created above:

    $ geany -c ~/.config/geany-avr 

To create a new directory that is pre-populated with code and Makefile 
templates, select "Build > New AVR Project".

The various 'make {something}' items under "Build" are (slighly) better 
documented in the Makefile you'll see after you do a "Build > New AVR Project" 
(or in this bundle at 'templates-generic/Makefile').

To re-generate tags used for autocompletion (e.g., because you have added a
new AVR library), select "Build > "Codetag generator script" and edit the
script as documented in the script. Then run the script with "Build > Execute". 
Note that the tags  produced by this script will apply to the entire profile, 
not just the project.

Use without Geany
-----------------
The 'avr-vew-project' scripts as well as the source code and Makefile templates
in  'templates-project' are generic in nature and can be used independently of
Geany. In this case no configuration is required; simply run the
'avr-vew-project' script.

License
-------
With exceptions, this project is licensed under a "three-clause BSD" license.
Licenses of individual files are given in the files themselves.

This document is Copyright (C) 2012 Mithat Konar. All rights reserved.

Redistribution and use of this document in source (plain text) and 'compiled' 
forms (PDF, PostScript, HTML, RTF, etc), with or without modification, are 
permitted provided that the following conditions are met:
    * Redistributions of source code (plain text) must retain the above 
      copyright notice, this list of conditions and the following disclaimer.
    * Redistributions in in compiled form (transformed to other DTDs, converted 
      to PDF, PostScript, HTML, RTF, and other formats) must reproduce the 
      above copyright notice, this list of conditions and the following 
      disclaimer in the documentation and/or other materials provided with the 
      distribution.
    * Neither the name of the <organization> nor the names of its contributors 
      may be used to endorse or promote products derived from this software 
      without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL <COPYRIGHT HOLDER> BE LIABLE FOR ANY
DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.