diff --git a/doc/uncategorized/README.md b/doc/uncategorized/README.md new file mode 100644 index 00000000..d6f07218 --- /dev/null +++ b/doc/uncategorized/README.md @@ -0,0 +1,9 @@ +# Uncategorized Documentation + +Any document in this directory may be moved in the future to +a more suitable location. This is a good place to put any +documentation that needs to be written when it's unclear what +the best place for it is. This is to avoid situations where +documentation _doesn't_ get written simply because it's not clear +where it belongs (something which the author of this very document +has been guilty of at times). diff --git a/doc/uncategorized/es6-note.md b/doc/uncategorized/es6-note.md new file mode 100644 index 00000000..3bbb050a --- /dev/null +++ b/doc/uncategorized/es6-note.md @@ -0,0 +1,46 @@ +# Notes about ES6 Class Syntax + +## Document Meta + +> **backend focus:** This documentation is more relevant to +> Puter's backend than frontend, but is placed here because +> it could apply to other areas in the future. + +## Expressions as Methods + +One important shortcoming in the ES6 class syntax to be aware of +is that it discourages the use of expressions as methods. + +For example: + +```javascript +class ExampleClass extends SomeBase { + intuitive_method_definition () {} + + constructor () { + this.less_intuitive = some_expr(); + } +} +``` + +Even if it is known that the return type of `some_expr` is a function, +it is still unclear whether it's being used as a callback or +as a method without other context in the code, since this is +how we typically assign instance members rather than methods. + +We solve this in Puter's backend using a **trait** called +[AssignableMethodsTrait](../../packages/backend/src/traits/AssignableMethodsTrait.js) +which allows a static member called `METHODS` to contain +method definitions. + +### Uses for Expressions as Methods + +#### Method Composition + +Method Composition is the act of composing methods from other +constituents. For example, +[Sequence](../../packages/backend/src/codex/Sequence.js) +allows composing a method from smaller functions, allowing +easier definition of "in-betwewen-each" behaviors and ways +to track which values from the arguments are actually read +during a particular call. diff --git a/doc/uncategorized/puter-mods.md b/doc/uncategorized/puter-mods.md new file mode 100644 index 00000000..271d5e99 --- /dev/null +++ b/doc/uncategorized/puter-mods.md @@ -0,0 +1,66 @@ +# Puter Mods + +## What is a Puter Mod? + +Currently, the definition of a Puter mod is: + +> A [Module](../../packages/backend/doc/contributors/modules.md) +> which is exported by a package directory which itself exists +> within a directory specified in the `mod_directories` array +> in `config.json`. + +## Enabling Puter Mods + +### Step 1: Update Configuration + +First update the configuration (usually at `./volatile/config.json` +or `/var/puter/config.json`) to specify mod directories. + +```json +{ + "config_name": "example config", + + "mod_directories": [ + "{source}/mods/mods_enabled" + ] + + // ... other config options +} +``` + +The first path you'll want to add is +`"{source}/mods/mods_enabled"` +which adds all the mods included in Puter's official repository. +You don't need to change `{source}` unless your entry javascript +file is in a different location than the default. + +If you want to enable all the mods, you can change the path above +to `mods_available` instead and skip step 2 below. + +### Step 2: Select Mods + +To enable a Puter mod, create a symbolic link (AKA symlink) in +`mods/mods_enabled`, pointing to +a directory in `mods/mods_available`. This follows the same convention +as managing sites/mods in Apache or Nginx servers. + +For example to enable KDMOD (which you can read as "Kernel Dev" mod, +or "the mod that GitHub user KernelDeimos created to help with testing") +you would run this command: +```sh +ln -rs ./mods/mods_available/kdmod ./mods/mods_enabled/ +``` + +This will create a symlink at `./mods/mods_enabled/kdmod` pointing +to the directory `./mods/mods_available/kdmod`. + +> **note:** here are some helpful tips for the `ln` command: +> - You can remember `ln`'s first argument is the unaffected +> source file by remembering `cp` and `mv` are the same in +> this way. +> - If you don't add `-s` you get a hard link. You will rarely +> find yourself needing to do that. +> - The `-r` flag allows you to write both paths relative to +> the directory from which you are calling the command, which +> is sometimes more intuitive. +