From 34c7fa8312f125ffd44d270a1dc42fbcd888f760 Mon Sep 17 00:00:00 2001 From: Tasia Iso Date: Sat, 11 May 2024 19:47:14 +0200 Subject: [PATCH] docs: new documentation --- README.md | 29 +------- docs/building.md | 75 +++++++++++++++++++++ docs/contributing.md | 33 +++++++++ docs/documentation.md | 17 +++++ docs/faq.md | 9 +++ docs/guide.md | 4 +- docs/guidelines/documentation-guidelines.md | 33 +++++++++ docs/running.md | 20 ++++++ 8 files changed, 191 insertions(+), 29 deletions(-) create mode 100644 docs/building.md create mode 100644 docs/contributing.md create mode 100644 docs/documentation.md create mode 100644 docs/faq.md create mode 100644 docs/guidelines/documentation-guidelines.md create mode 100644 docs/running.md diff --git a/README.md b/README.md index 2ba21b85..53eddba0 100644 --- a/README.md +++ b/README.md @@ -14,36 +14,11 @@ Scuttlebutt, as well as a platform for writing and running web applications. 3. Make creating and sharing web applications accessible to anyone with a browser. -## Building - -Builds on Linux (x86_64 and aarch64), MacOS, OpenBSD, and Haiku. Builds for -all of those host platforms plus mingw64, iOS, and android. - -1. Requires openssl (`libssl-dev`, in debian-speak). All other dependencies - are kept up to date in the tree. -2. To build, run `make debug` or `make release`. An executable will be - generated in a subdirectory of `out/`. -3. It's possible to build for Android, iOS, and Windows on Linux, if you have - the right dependencies in the right places. `make windebug winrelease -iosdebug-ipa iosrelease-ipa release-apk`. -4. To build in docker, `docker build .`. -5. `make format` will normalize formatting to the coding standard. - -## Running - -By default, running the built `tildefriends` executable will start a web server -at . `tildefriends -h` lists further options. - -The first user to create an account and log in will be granted administrative -privileges. Further administration can be done at -. - ## Documentation -Docs are a work in progress: -. +Docs are a work in progress in the `docs` folder and in Tilde Friends: . ## License All code unless otherwise noted in is provided under the -[MIT](https://opensource.org/licenses/MIT) license. +[MIT](https://opensource.org/licenses/MIT/) license. diff --git a/docs/building.md b/docs/building.md new file mode 100644 index 00000000..a2d4a62c --- /dev/null +++ b/docs/building.md @@ -0,0 +1,75 @@ +# How to build Tilde Friends + +> Disclaimer: this documentation has been written by a Linux user and has not been reviewed by other people on other platforms. The procedure may vary slightly depending on your operating system. + +Builds **on** Linux (`x86_64` and `aarch64`), MacOS, OpenBSD, and Haiku. + +Builds **for** all of those host platforms plus `mingw64`, iOS, and android. + +Dependencies: + +- `openssl` (`libssl-dev`, in debian-speak) + +Dependencies for Android: + +- TODO + +Dependencies for iOS: + +- TODO + +Dependencies for Windows: + +- TODO + +> All other dependencies are kept up to date as git submodules. + +1. Clone the repository with the submodules: `git clone --recursive https://dev.tildefriends.net/cory/tildefriends.git` + +2. Run `make -j $(nproc) debug` or `make -j $(nproc) release` + +> If you're unsure whether you should choose `debug` or `release`, stick to `release`. + +> `-j $(nproc)` will start a compiler for every CPU thread, which will dramatically reduce the time needed to compile Tilde Friends. + +An executable will be generated in a subdirectory of `out/` + +It's possible to build for Android, iOS, and Windows on Linux, if you have the right dependencies in the right places. Run `make -j $(nproc) windebug winrelease iosdebug-ipa iosrelease-ipa release-apk` + +To build in docker, `docker build .` + +On NixOS: TODO + +Now that you have a binary, head over to . + +## Troubleshooting + +### The compiler throws an error and I can't build the binary. + +Open `GNUMakefile` and edit the CFLAGS environment variable around line 50. + +For example given this error: + +``` +src/http.c: In function ‘tf_http_get_cookie’: +src/http.c:1089:128: error: check of ‘name’ for NULL after already dereferencing it [-Werror=analyzer-deref-before-check] +``` + +Add: + +```diff +CFLAGS += \ + -std=gnu11 \ + -Wall \ + -Wextra \ + -Wno-unused-parameter \ ++ -Wno-analyzer-deref-before-check \ + -MMD \ + -MP \ + -ffunction-sections \ + -fdata-sections \ + -fno-exceptions \ + -g +``` + +Now the compiler will ignore this error and *should* continue building anyways. diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 00000000..554c1436 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,33 @@ +# How to contribute + +- Fork this repository + +- Clone your repository + +Alternatively, you can change the `origin` remote on your existing clone: + +`git remote set-url origin https://dev.tildefriends.net/YOUR_USERNAME/tildefriends.git` + +- Make your changes + + - I want to edit C code ! + + - I want to edit JavaScript code ! + + - I want to write documentation ! + + Great! Before you do, have a look at the [documentation guidelines](guidelines/documentation-guidelines.md) to learn how to write consistent documentation. + +- Format your changes: + +If you've edited C code: run `make format` + +If you've edited JavaScript code or the documentation: run `npm run format` + +- Open a pull request + +TODO + +- Get your changes reviewed and merged + +TODO diff --git a/docs/documentation.md b/docs/documentation.md new file mode 100644 index 00000000..2fc7a476 --- /dev/null +++ b/docs/documentation.md @@ -0,0 +1,17 @@ +# Tilde Friends documentation + +## Building + +See . + +## Contibuting + +See . + +## FAQ / Troubleshooting + +See . + +## Guide + +See . diff --git a/docs/faq.md b/docs/faq.md new file mode 100644 index 00000000..67d2f29a --- /dev/null +++ b/docs/faq.md @@ -0,0 +1,9 @@ +# Troubleshooting + +## I started tildefriends. Now what ? + +See . + +### The compiler throws an error and I can't build the binary. + +See . diff --git a/docs/guide.md b/docs/guide.md index f4aaa57c..f815f911 100644 --- a/docs/guide.md +++ b/docs/guide.md @@ -18,7 +18,7 @@ Above the terminal, an "Edit" link brings a visitor to the source code for the current Tilde Friends application, which they can then edit, save as their own, and run. -# Architecture +## Architecture Tilde Friends is a C++ application with a JavaScript runtime that provides restricted access to filesystem, network, and other system resources. The core @@ -66,7 +66,7 @@ performance reasons to minimize the data size transferred between processes. // Receive the above message and call the function. core.register("onMessage", function(sender, message) { - message.add(3, 4).then(x => terminal.print(x.toString())); + message.add(3, 4).then(x => terminal.print(x.toString())); }); Finally, there is a core web interface that runs on the client's browser that diff --git a/docs/guidelines/documentation-guidelines.md b/docs/guidelines/documentation-guidelines.md new file mode 100644 index 00000000..1be46d20 --- /dev/null +++ b/docs/guidelines/documentation-guidelines.md @@ -0,0 +1,33 @@ +# Documentation guidelines + +This document defines the rules used to write documentation in order to make it more consistent. + +This documentation is a living document and so are it's rules; you are free to propose changes but in the meantime, please stick to them. + +The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC 2119](https://www.rfc-editor.org/rfc/rfc2119/). + +## File naming + +Files SHOULD be named using [kebab-case](https://www.freecodecamp.org/news/snake-case-vs-camel-case-vs-pascal-case-vs-kebab-case-whats-the-difference/#kebab-case). + +Their names should be meaningful and SHOULD not conflict with other files in other directories: + +> Example: this document is named `docs/guidelines/documentation-guidelines.md` instead of `docs/guidelines/documentation.md` because it could cause confusion with `docs/documentation.md`. + +## Documentation + +When writing documentation, the author should have in mind it's target audience: people with varying technical skills and backgrounds, fluency in peer-to-peer-specific terms and mental ability. The documentation should therefore be acessible and usefule to most people interested in building, using and contributing to Tilde Friends. + +### Terminology + +`Tilde Friends` refers to the projectas a whole. This can be abbreviated to `TF`. + +`tildefriends` refers to the program. + +### Style guide + +TODO + +## License + +As per the rest of the code in this repository, the documentation is shared under the [MIT](https://opensource.org/licenses/MIT/) license. diff --git a/docs/running.md b/docs/running.md new file mode 100644 index 00000000..ed790d57 --- /dev/null +++ b/docs/running.md @@ -0,0 +1,20 @@ +# Running Tilde Friends + +> Disclaimer: this documentation has been written by a Linux user and has not been reviewed by other people on other platforms. The procedure may vary slightly depending on your operating system. + +The binaries should appear at `out/debug/tildefriends` and `out/release/tildefriends`. + +For Android, iOS and Windows: TODO + +You can start the server by running `./out/debug/tildefriends` or `./out/release/tildefriends`. + +By default, running the built `tildefriends` executable will start a web server +at . `tildefriends -h` lists further options. + +The first user to create an account and log in will be granted administrative +privileges. Further administration can be done at +. + +## How to use TF + +TODO