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

I am aware of the s3fs code from Randy Rizun <[email protected]>. However, that
code relies on OpenSSL whose license conflicts with the GPL, and it seems to
have problems supporting buckets that are not stored on the Standard US server.
My impression of the quality of the code made me decide to implement aws-s3fs
from scratch rather than attempting to patch Randy Rizun's code. aws-s3fs
honors the s3fs metaheaders on the S3 drive, however, so permissions and other
file attributes should remain identical regardless of your choice of s3fs or
aws-s3fs.


== 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, you'll 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 aws-s3fs 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 aws-s3fs_(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 software design is documented in doc/Design.odt, which is readable by
the LibreOffice Writer.

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 doxygen

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 aws-s3fs
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

The tests include live tests that communicate with an Amazon S3 bucket host.
These tests require a configuration file with authentication data and the
following setup:

    * Upload the README file to the top folder of your S3 bucket.

    * Create a folder named "directory" in the top folder of your S3 bucket.

    * Upload the COPYING file into the "directory" folder you just created.

    * Create a folder named "directory2" in the "directory" folder.

    * Upload some file (anything is okay) into "directory2".

    * The live tests will be performed if a configuration file named
      "livetest.ini" is found in test/testdata. Copy the file named
      livetest.ini.example in the testdata directory to livetest.ini and
      edit the latter to match your own S3 settings.

    Do not attempt to modify the properties of the files with amz-meta headers;
    just use the AWS console to create the files.

    Your file structure on the S3 drive should now look like this:

       <your-bucket-name>/README
       <your-bucket-name>/directory/
       <your-bucket-name>/directory/COPYING
       <your-bucket-name>/directory/directory2/
       <your-bucket-name>/directory/directory2/<whatever file or files>


== 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
aws-s3fs 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).


Thanks to:

 * Timothy Kay <http://timkay.com/> for providing the aws script, which served
   as inspiration and gave name to the package.

 * Ulrich Drepper <[email protected]> for releasing MD5 message digest
   functions under a GPL license.

 * Paul E. Jones <[email protected]> for releasing SHA1 message digest
   functions under a freeware license.

 * Joseph J. Pfeiffer <[email protected]> for creating a FUSE tutorial with
   accompanying code.

Report bugs to: Ole Wolf <[email protected]>.


---

Copyright: 2012 Ole Wolf <[email protected]>
License: GPL-3+

This file is part of aws-s3fs.

aws-s3fs 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".