siriushq/midio
==============

There are many available sources of documentation for users and contributors.
Non-rendered source documentation is available in the "documentation" directory.
https://midio.sirius.cam houses the rendered documentation.

It is mandatory to read [license] & [/attribution/*] before using this software.

<!> The rendered documentation is currently not public.
<!> A release has not yet been published, you must manually build.

building
========

The preferred environment uses Git and Go 1.19.
Go distribution is provided by go-wrapper <git@github.com:furkilic/go-wrapper>.

Ensure that GOROOT is unset, or your local Go installation may take precedence.
Always test the [gow version] command to ensure this is not the case.

Ensure the [.git] directory is preserved (clone the repository correctly),
or building will fail.

	building binary ====================================================
	$ git clone --recursive git@github.com:siriushq/midio.git
	$ cd midio
	$ gow generate
	$ gow build -ldflags="-s -w"

	This produces a runnable binary, for the system you are building on.
	For usage instructions, execute the binary.
	====================================================================

	building licenses ================================================
	$ gow install github.com/google/go-licenses/v2@v2.0.0
	$ go-licenses report github.com/siriushq/midio \
		--template ./attribution/license-dependencies.tpl \
		> ./attribution/license-dependencies.md

	Swap line continuations ('\') for the shell you are building with.
	==================================================================

	building as shared library ========================================
	$ gow generate
	$ gow build -ldflags="-s -w" --buildmode=c-shared -o midio.SO

	Swap 'SO' (for Unix) with 'DLL' (for Windows) or 'DYLIB' (for Mac).
	This produces a binary and C header file, for the desired system.
	Below is a usage example:

		#include "midio.h"

		midio_builder builder = midio_create();
		midio_volume(builder, "./example/");

		midio server = midio_server(builder);
		while (1) {
			char* message = midio_message();
			printf("%s", message);
			free(message);
		}
	===================================================================

	building documentation =======================================
	The documentation is automatically built on the master branch.
	For a local preview server, install Bun and run the following:

	$ cd /docs/
	$ bunx mint dev
	==============================================================

	running test suite ===================================================
	This can take a long time to run.
	Your firewall may block any opened ports when running it.

	This is required to be ran, and both binary & shared library builds
	tested manually, before any patches are submitted (when contributing).

	$ gow test ./...
	======================================================================

contributing
============

Contributions are accepted as long as they fall within implied project scope.

All commits must contain at least `Signed-off-by` to identify the author of the
contribution, and may contain `Co-authored-by` to attach any number of other
authors (this can be added automatically with `git commit ... -s ...`).

(furthermore, commits from people with repository write access are to be signed
with a verified GPG, SSH or S/MIME signature attached to your GitHub account).

Relevant documentation should be updated to include accrediting.

By submitting a contribution, you certify that you and other authors are making
your contribution available under the license of the project, and that you have
the rights to submit it.

licensing
=========

This project is licensed under the 3-Clause BSD.
This is being done at our loss. Consider starring this repository and/or buying
our products to support the development and future of this project.

Some portions of this project are adapted from projects with other licenses.
They are clearly marked with `SPDX-License-Identifier` & declared in the
"/attribution/*" directory.

support
=======

If commercial support is required, it can be granted for users/organizations by
request. Responses will be provided within 24 hours.

This can be obtained by emailing `midio@mechite.com` with the following
(* for required; please fill all fields using "N/A" for empty optionals):

	example.eml ==============================
	To: <midio@mechite.com>
	Subject: siriushq/midio commercial support
	Content-Type: text/plain; charset="UTF-8"

	Name *
	Organization
	Role

	Minimum duration commitment required
	Earliest required start date
	==========================================