WIP: Write documentation #55

Draft
tasiaiso wants to merge 22 commits from tasiaiso/tildefriends:tasiaiso-documentation into main
8 changed files with 191 additions and 29 deletions
Showing only changes of commit 34c7fa8312 - Show all commits

View File

@ -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 <http://localhost:12345/>. `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
<http://localhost:12345/~core/admin/>.
## Documentation
Docs are a work in progress:
<https://www.tildefriends.net/~cory/wiki/#test-wiki/tf-app-quick-reference>.
Docs are a work in progress in the `docs` folder and in Tilde Friends: <https://www.tildefriends.net/~cory/wiki/#test-wiki/tf-app-quick-reference>.
## 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.

75
docs/building.md Normal file
View File

@ -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
Review

@cory can you help me fill those in ?

@cory can you help me fill those in ?
Dependencies for iOS:
- TODO
Review

same

same
Dependencies for Windows:
- TODO
Review

same

same
> 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 <running.md>.
## 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.

33
docs/contributing.md Normal file
View File

@ -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

17
docs/documentation.md Normal file
View File

@ -0,0 +1,17 @@
# Tilde Friends documentation
## Building
See <building.md>.
## Contibuting
See <contributing.md>.
## FAQ / Troubleshooting
See <faq.md>.
## Guide
See <guide.md>.

9
docs/faq.md Normal file
View File

@ -0,0 +1,9 @@
# Troubleshooting
## I started tildefriends. Now what ?
See <running.md>.
### The compiler throws an error and I can't build the binary.
See <building.md>.

View File

@ -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

View File

@ -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.

20
docs/running.md Normal file
View File

@ -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
Review

@cory I need help for that too

@cory I need help for that too
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 <http://localhost:12345/>. `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
<http://localhost:12345/~core/admin/>.
## How to use TF
TODO