Merge pull request #105 from saxbophone/develop

Version 0.19.0 - That which will be open-sourced

CMakeLists.txt

@@ -1,7 +1,29 @@
+# This source file forms part of libsaxbospiral, a library which generates
+# experimental 2D spiral-like shapes based on input binary data.
+#
+# This is the CMake build file for libsaxbospiral.
+# It requires CMake v3.0 or greater.
+#
+#
+#
+# Copyright (C) 2016, Joshua Saxby joshua.a.saxby+TNOPLuc8vM==@gmail.com
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License (version 3),
+# as published by the Free Software Foundation.
+#
+# 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 Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
 # begin basic metadata
 cmake_minimum_required(VERSION 3.0)
 
-project(libsaxbospiral VERSION 0.18.0 LANGUAGES C)
+project(libsaxbospiral VERSION 0.19.0 LANGUAGES C)
 set(CMAKE_C_STANDARD 99)
 set(CMAKE_C_STANDARD_REQUIRED ON)
 set(

CONTRIBUTING.md

@@ -0,0 +1,38 @@
+# libsaxbospiral - Contributing
+
+Thanks for considering contributing to libsaxbospiral!
+
+Here are some tips and general info about contributing to this project. Following these tips will increase the likelihood of getting a speedy PR :smile:
+
+## Checklist
+
+Before you contribute, check the work you're about to do fulfils one of these criteria:
+
+1. Implements a feature represented by an accepted issue in the project's [Github issue tracker](https://github.com/saxbophone/libsaxbospiral/issues)
+2. Fixes a bug you discovered (preferably an issue should be created too, but for small or critical bugs, this may not be needed).
+
+Please also check that the work is not already being undertaken by someone else.
+
+## Code Style
+
+I haven't yet formalised the style guide for this project, but this is something I plan to do in the future. Until then, if you could try your best to follow the style of existing code, that will help a great deal.
+
+In addition, please make sure:
+
+- You commit files with Unix Line-endings (`\n` `<LF>` `0x0a`)
+- Each text file committed has a trailing newline at the end
+- C source code is indented with 4 spaces per indentation level (no tabs)
+- Public functions are prototyped in the correct C Header file, all private declarations are declared `static`
+- Every public function (and ideally private too) has an accompanying explanatory comment
+
+## Testing
+
+The unit tests for libsaxbospiral currently all reside in one C source file, `tests.c`. This isn't ideal, and I'm planning to clean these up at some point. Build and run the unit tests when you first pull down the code, rebuild and run them again when you've made your changes. Changes adding larger pieces of functionality will likely have additional tests requested for them, or an offer made to write the tests for them.
+
+Pull requests will also *soon* be going through [Travis CI](https://travis-ci.org/) for automated testing.
+
+## Transfer of Copyright
+
+I've yet to create a CLA (Contributor License Agreement), but I will likely be doing so soon and definitely when I start getting external contributions.
+
+This will likely involve aggreeing of transfer of copyright ownership of contributed work to me (Joshua Saxby/@saxbophone), so I can be in the best position to defend copyright claims against me and also allow for dual-licensing should someone find this commercially valuable.

README.md

@@ -1,10 +1,40 @@
 # libsaxbospiral ![libsaxbospiral](libsaxbospiral.png "libsaxbospiral")
 
+![AGPL v3 Logo](agplv3-155x51.png "A logo used to show the AGPL v3.0 License")
+
 Experimental generation of 2D spiralling lines based on input binary data.
 
-This is a library only, if you're looking for something that is immediately usable for the end-user, you probably want to look at [sxbp](https://github.com/saxbophone/sxbp) instead.
+This a C library implementing an experimental idea I had for generating procedural shapes. The library takes input as sequences of bytes and turns the 1s and 0s into a kind of *right-angled spiral*, with the changes in direction of the line encoding the binary data in a lossless manner.
+
+For example, the input text **`cabbages`**, encoded as ASCII gives us the following byte values:
+
+**`0x63 0x61 0x62 0x62 0x61 0x67 0x65 0x73`**
+
+When this is given as input data to the algorithm, the output is the shape shown below:
+
+!['cabbages', shown as a saxbospiral figure from encoded ASCII](example_01_cabbages.png "cabbages', shown as a saxbospiral figure from encoded ASCII")
+
+The algorithm is not limited to text however - any form of input binary data will work to produce a resulting figure, although the length of input data currently is a limiting factor in getting speedy results, if perfection is desired.
+
+## Please Note
+
+- This is a library only. If you're looking for something that is immediately usable for the end-user, you probably want to look at [sxbp](https://github.com/saxbophone/sxbp) instead, which is a command-line program I wrote which uses libsaxbospiral to render input binary files to PNG images.
 
-## Dependencies
+- As libsaxbospiral is currently at major version 0, expect the library API to be unstable. I will endeavour as much as possible to make sure breaking changes increment the minor version number whilst in the version 0.x.x series and bugfixes increment the patch version number, but no heavy reliance should be placed on this.
+
+## Licensing
+
+Libsaxbospiral is released under version **3.0** of the **GNU Affero General Public License** (AGPLv3).
+
+A full verbatim of this license may be found in the [LICENSE](LICENSE) file in this repository. *You should almost certainly read it*. If for some reason you have not received this file, you can view a copy of the license at [http://www.gnu.org/licenses/](http://www.gnu.org/licenses/).
+
+Note that as well as being under the same copyleft protections as the GPL License, the AGPL enforces these protections further by **including provision of the software via a network service (such as a website) as one of its definitions of distribution**, hence requiring those who integrate libsaxbospiral into their website or other network service to also release the software into which they are integrating libsaxbospiral under this same license (AGPLv3).
+
+## Building + Installing
+
+Libsaxbospiral can be built without installing for test purposes and for general usage, however if you plan on writing programs that use it I recommend you install it so it will be in your system's standard library and header include locations.
+
+### Dependencies
 
 You will need:
 
@@ -16,34 +46,45 @@ You will need:
 
 > These commands are for unix-like systems, without an IDE or other build system besides CMake. If building for a different system, or within an IDE or other environment, consult your IDE/System documentation on how to build CMake projects.
 
-> Additionally, it is of worth noting that this library has only been thoroughly tested and developed on **Ubuntu GNU/Linux** with **GCC v5.4.0**, although every effort has been made to make it as cross-platform as possible (including reasonably strict **ISO C 99** compliance). It should compile under any POSIX-compliant system with the correct additional dependencies listed. **v0.8** is known to successfully cross-compile from Ubuntu to Windows (via [cygwin](https://www.cygwin.com/)) and Max OSX (using a locally-built compiler toolchain provided via [OSXCross](https://github.com/tpoechtrager/osxcross). It is highly likely that all other versions cross-compile as well (but I haven't yet verified this).
-
-## Basic Build
-
-```sh
-cmake .
-make
-```
+> Additionally, it is of worth noting that this library has only been thoroughly tested and developed on **Ubuntu GNU/Linux** with **GCC v5.4.0** and **Clang 3.8.0**. Although every effort has been made to make it as cross-platform as possible (including quite strict **ISO C 99** compliance), **Your Mileage May Vary**. Bug Reports and Patches for problems running on other systems, particularly **Microsoft Windows** and **Mac OSX** are most welcome.
 
 ## Recommended Library Build
 
-Add two custom options to CMake to build the library in release mode (with full optimisation) and as a shared dynamic library:
+Invoke CMake within the root of this repository, with these arguments to make CMake build the library in release mode (with full optimisation) and as a shared library:
 
 ```sh
 cmake -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=ON .
 make
 ```
 
+> ### Note:
+
+> Building as a shared library is recommended as then binaries compiled from [sxbp](https://github.com/saxbophone/sxbp) or your own programs that are linked against the shared version can immediately use any installed upgraded versions of libsaxbospiral with compatible ABIs without needing re-compiling.
+
 ## Test
 
+Building the library with the default Make target shown above also compiles the unit tests for libsaxbospiral, to an executable in the same directory. You can either run this directly, use `make test` or use **ctest** (comes bundled with CMake) to run these unit tests (recommended):
+
 ```sh
-make test
+ctest -V  # get verbose output from test running
 ```
 
+> ### Note:
+
+> It's recommended that if testing for development purposes (rather than just verification that all is working), you run CMake in `Debug` mode instead. This will pass more strict options to your compiler if it supports them (GCC and Clang do), leading to a higher chance of bugs being caught before commital.
+
 ## Install Library
 
-This command might require `sudo`, but check your system configuration. For example, it installs to `/usr/local/` by default, which is user-writable on OSX if you use Homebrew, so not requiring admin privileges.
+Use the `make install` target to install the compiled library and the neccessary header files to your system's standard location for these files.
 
 ```
 make install
 ```
+
+> ### Note:
+
+> This may or may not require admin priveleges. Typically does on GNU/Linux, typically doesn't on Mac OSX *with Homebrew installed* and *probably doesn't* on Microsoft Windows.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for information related to making contributions to libsaxbospiral.

saxbospiral/initialise.c

@@ -1,3 +1,25 @@
+/*
+ * This source file forms part of libsaxbospiral, a library which generates
+ * experimental 2D spiral-like shapes based on input binary data.
+ *
+ * This compilation unit provides basic functions to initialise a spiral.
+ *
+ *
+ *
+ * Copyright (C) 2016, Joshua Saxby joshua.a.saxby+TNOPLuc8vM==@gmail.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License (version 3),
+ * as published by the Free Software Foundation.
+ *
+ * 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
 #include <stdint.h>
 #include <stdlib.h>
 

saxbospiral/initialise.h

@@ -1,3 +1,25 @@
+/*
+ * This source file forms part of libsaxbospiral, a library which generates
+ * experimental 2D spiral-like shapes based on input binary data.
+ *
+ * This compilation unit provides basic functions to initialise a spiral.
+ *
+ *
+ *
+ * Copyright (C) 2016, Joshua Saxby joshua.a.saxby+TNOPLuc8vM==@gmail.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License (version 3),
+ * as published by the Free Software Foundation.
+ *
+ * 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
 #ifndef SAXBOPHONE_SAXBOSPIRAL_INITIALISE_H
 #define SAXBOPHONE_SAXBOSPIRAL_INITIALISE_H
 

saxbospiral/plot.c

@@ -1,3 +1,26 @@
+/*
+ * This source file forms part of libsaxbospiral, a library which generates
+ * experimental 2D spiral-like shapes based on input binary data.
+ *
+ * This compilation unit provides functions for plotting and caching the points
+ * which make up the lines of a spiral.
+ *
+ *
+ *
+ * Copyright (C) 2016, Joshua Saxby joshua.a.saxby+TNOPLuc8vM==@gmail.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License (version 3),
+ * as published by the Free Software Foundation.
+ *
+ * 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
 #include <stdlib.h>
 
 #include "saxbospiral.h"

saxbospiral/plot.h

@@ -1,3 +1,26 @@
+/*
+ * This source file forms part of libsaxbospiral, a library which generates
+ * experimental 2D spiral-like shapes based on input binary data.
+ *
+ * This compilation unit provides functions for plotting and caching the points
+ * which make up the lines of a spiral.
+ *
+ *
+ *
+ * Copyright (C) 2016, Joshua Saxby joshua.a.saxby+TNOPLuc8vM==@gmail.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License (version 3),
+ * as published by the Free Software Foundation.
+ *
+ * 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
 #ifndef SAXBOPHONE_SAXBOSPIRAL_PLOT_H
 #define SAXBOPHONE_SAXBOSPIRAL_PLOT_H
 

saxbospiral/render.c

@@ -1,3 +1,26 @@
+/*
+ * This source file forms part of libsaxbospiral, a library which generates
+ * experimental 2D spiral-like shapes based on input binary data.
+ *
+ * This compilation unit provides functions for rendering a spiral to a bitmap.
+ *
+ *
+ *
+ * Copyright (C) 2016, Joshua Saxby joshua.a.saxby+TNOPLuc8vM==@gmail.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License (version 3),
+ * as published by the Free Software Foundation.
+ *
+ * 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
 // sanity check for support of 64-bit integers
 #if __SIZEOF_SIZE_T__ < 8
 #warning "Please compile this code for a target with 64-bit words or greater."

saxbospiral/render.h

@@ -1,3 +1,25 @@
+/*
+ * This source file forms part of libsaxbospiral, a library which generates
+ * experimental 2D spiral-like shapes based on input binary data.
+ *
+ * This compilation unit provides functions for rendering a spiral to a bitmap.
+ *
+ *
+ *
+ * Copyright (C) 2016, Joshua Saxby joshua.a.saxby+TNOPLuc8vM==@gmail.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License (version 3),
+ * as published by the Free Software Foundation.
+ *
+ * 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
 #ifndef SAXBOPHONE_SAXBOSPIRAL_RENDER_H
 #define SAXBOPHONE_SAXBOSPIRAL_RENDER_H
 

saxbospiral/render_backends/png_backend.c

@@ -1,3 +1,25 @@
+/*
+ * This source file forms part of libsaxbospiral, a library which generates
+ * experimental 2D spiral-like shapes based on input binary data.
+ *
+ * This compilation unit provides functionality to render a bitmap struct to PNG
+ *
+ *
+ *
+ * Copyright (C) 2016, Joshua Saxby joshua.a.saxby+TNOPLuc8vM==@gmail.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License (version 3),
+ * as published by the Free Software Foundation.
+ *
+ * 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
 #include <stdlib.h>
 #include <string.h>
 

saxbospiral/render_backends/png_backend.h

@@ -1,3 +1,25 @@
+/*
+ * This source file forms part of libsaxbospiral, a library which generates
+ * experimental 2D spiral-like shapes based on input binary data.
+ *
+ * This compilation unit provides functionality to render a bitmap struct to PNG
+ *
+ *
+ *
+ * Copyright (C) 2016, Joshua Saxby joshua.a.saxby+TNOPLuc8vM==@gmail.com
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License (version 3),
+ * as published by the Free Software Foundation.
+ *
+ * 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 Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ */
 #ifndef SAXBOPHONE_SAXBOSPIRAL_PNG_BACKEND_H
 #define SAXBOPHONE_SAXBOSPIRAL_PNG_BACKEND_H