This README contains notes for packagers
----------------------------------------

PLEASE NOTE: this code is currently under development and does not yet
provide any useful functionality.


Copyright: 2012 Ole Wolf <wolf@blazingangles.com>
License: GPL-3+

This file is part of gtasks2ical.

gtasks2ical is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

On Debian systems, the complete text of the GNU General Public
License version 3 can be found in "/usr/share/common-licenses/GPL-3".


== Quick Start ==

Install the software (see the next section, _Installing_).

Create a project at https://code.google.com/apis/console, ticking the "Tasks"
API service.  Then create an OAuth 2.0 client ID for an installed application.
Make a note of the "Client ID" and the "Client secret" strings.

Create the file ~/.gtasks2icalrc with the following contents:

  [local]
  client id      = <Client ID string>
  client secret  = <Client secret string>
  gmail user     = <yourusername@gmail.com>
  gmail password = <your Gmail password>
  ipv4 only      = true

This setting will allow you to, e.g., download your Google Tasks into the
directory named "mycal" with the following command:

  gtasks2ical -d "Default List" mycal


== Installing ==

The package is intended to be installed via the Debian packaging system,
which takes care of installing configuration files, log rotation scripts,
etc. To create a Debian package, install the debhelper tools and execute:

    debuild

in the top directory (i.e., the folder with the README file).

The autoconf tool should install the files properly, too, using the standard
./configure; make; make install procedure. If you elect to attempt the vanilla
autoconf installation procedure where the "configure" script has not yet been
generated, you will first need to run:

    $ ./autoreconf -i

in the root directory of the package in order to create the necessary files
for building and installing with autoconf.

If you downloaded gtasks2ical from the git source, then there already is a
./debian directory with properly configured files; however, the original
source code tarball is not included. You may build the tarball yourself via
the debhelper tools, or you can execute the script:

    $ sh script/build-source-tarball.sh

which creates an gtasks2ical_(version).orig.tar.xz tarball with the current
source. This is not recommended, but I used the script during development
to avoid repeatedly patching the source with "dpkg-source --commit".

I have no idea how to package the code for other systems, but feel free to
provide patches that will enable other build systems.


== Source Code Documentation ==

The code is documented with Doxygen comments. The documentation is built
automatically in doc/doxygen if "make" is run and the build has been configured
with the option:

    $ ./configure --enable-doc

Otherwise you may build the documentation manually by issuing the command:

    $ make doc

in the top directory.

The documentation generation requires Doxygen and GraphViz, so make sure they
are installed. Navigate to doc/doxygen/index.html with your browser to view the
documentation.


== Test Issues ==

To run the autotest suite, type:

    $ make check

in the top directory.

The build requirements include the OpenSSL executable; this is not strictly
a requirement for the build itself, but the cryptographic tests use OpenSSL
for verification during "make check". There is no OpenSSL code in the
gtasks2ical source or executable, however, as the GPL requirements would
violate the OpenSSL license. To skip OpenSSL tests, configure the build with
the following option:

    $ ./configure --disable-openssltest


== Lint ==

The code will eventually be released as lint clean, with intentional overrides
included in the source code where appropriate. Most of these overrides are
currently related to intentional NULL pointers.

I intend to also check the code with rats, flawfinder, and pscan prior to
a formal release. There currently are issues related to buffer overrun risks,
but they are fairly easy to spot and in many cases are contained within the
gtasks2ical code (that is, a location with a theoretical buffer overrun issue
will receive input only from functions that are known to produce string output
that is within the buffer size limits).


== Software Defects ==

Report bugs to: Ole Wolf <wolf@blazingangles.com>.