You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Thanks for considering contributing to libsaxbospiral!
4
+
5
+
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:
6
+
7
+
## Checklist
8
+
9
+
Before you contribute, check the work you're about to do fulfils one of these criteria:
10
+
11
+
1. Implements a feature represented by an accepted issue in the project's [Github issue tracker](https://github.com/saxbophone/libsaxbospiral/issues)
12
+
2. Fixes a bug you discovered (preferably an issue should be created too, but for small or critical bugs, this may not be needed).
13
+
14
+
Please also check that the work is not already being undertaken by someone else.
15
+
16
+
## Code Style
17
+
18
+
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.
19
+
20
+
In addition, please make sure:
21
+
22
+
- You commit files with Unix Line-endings (`\n``<LF>``0x0a`)
23
+
- Each text file committed has a trailing newline at the end
24
+
- C source code is indented with 4 spaces per indentation level (no tabs)
25
+
- Public functions are prototyped in the correct C Header file, all private declarations are declared `static`
26
+
- Every public function (and ideally private too) has an accompanying explanatory comment
27
+
28
+
## Testing
29
+
30
+
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.
31
+
32
+
Pull requests will also *soon* be going through [Travis CI](https://travis-ci.org/) for automated testing.
33
+
34
+
## Transfer of Copyright
35
+
36
+
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.
37
+
38
+
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.
![AGPL v3 Logo](agplv3-155x51.png"A logo used to show the AGPL v3.0 License")
4
+
3
5
Experimental generation of 2D spiralling lines based on input binary data.
4
6
5
-
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.
7
+
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.
8
+
9
+
For example, the input text **`cabbages`**, encoded as ASCII gives us the following byte values:
10
+
11
+
**`0x63 0x61 0x62 0x62 0x61 0x67 0x65 0x73`**
12
+
13
+
When this is given as input data to the algorithm, the output is the shape shown below:
14
+
15
+
!['cabbages', shown as a saxbospiral figure from encoded ASCII](example_01_cabbages.png"cabbages', shown as a saxbospiral figure from encoded ASCII")
16
+
17
+
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.
18
+
19
+
## Please Note
20
+
21
+
- 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.
6
22
7
-
## Dependencies
23
+
- 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.
24
+
25
+
## Licensing
26
+
27
+
Libsaxbospiral is released under version **3.0** of the **GNU Affero General Public License** (AGPLv3).
28
+
29
+
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/).
30
+
31
+
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).
32
+
33
+
## Building + Installing
34
+
35
+
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.
36
+
37
+
### Dependencies
8
38
9
39
You will need:
10
40
@@ -16,34 +46,45 @@ You will need:
16
46
17
47
> 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.
18
48
19
-
> 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).
20
-
21
-
## Basic Build
22
-
23
-
```sh
24
-
cmake .
25
-
make
26
-
```
49
+
> 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.
27
50
28
51
## Recommended Library Build
29
52
30
-
Add two custom options to CMake to build the library in release mode (with full optimisation) and as a shared dynamic library:
53
+
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:
> 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.
63
+
37
64
## Test
38
65
66
+
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):
67
+
39
68
```sh
40
-
make test
69
+
ctest -V # get verbose output from test running
41
70
```
42
71
72
+
> ### Note:
73
+
74
+
> 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.
75
+
43
76
## Install Library
44
77
45
-
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.
78
+
Use the `make install` target to install the compiled library and the neccessary header files to your system's standard location for these files.
46
79
47
80
```
48
81
make install
49
82
```
83
+
84
+
> ### Note:
85
+
86
+
> 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.
87
+
88
+
## Contributing
89
+
90
+
See [CONTRIBUTING.md](CONTRIBUTING.md) for information related to making contributions to libsaxbospiral.
0 commit comments