From 76c83183a49465ff42fd869eaa2edf9cae56f0fa Mon Sep 17 00:00:00 2001 From: Peter Harpending Date: Thu, 12 Oct 2023 01:14:14 -0600 Subject: [PATCH] docs --- jrx/README.md | 8 +++++ utils/jex/README.md | 76 ++++++++++++++++++++++++++++++++++++++------- 2 files changed, 72 insertions(+), 12 deletions(-) diff --git a/jrx/README.md b/jrx/README.md index 0628ad3..e274a8e 100644 --- a/jrx/README.md +++ b/jrx/README.md @@ -3,6 +3,14 @@ This is a browser extension wallet for the Aeternity payment network. It is meant to work in the latest versions of Firefox and Chromium. +## Building + +Requires [jex](../utils/jex). + +``` +jex dwim- +``` + ## How it works You may want to read about how [AWCP](../libs/awcp/src/awcp.ts) and diff --git a/utils/jex/README.md b/utils/jex/README.md index 0536d07..46caccd 100644 --- a/utils/jex/README.md +++ b/utils/jex/README.md @@ -1,20 +1,13 @@ # Jex: simple TypeScript/JavaScript packaging system -Jex is a simple packaging/dependency system for TypeScript/JavaScript -projects. - -Jex is very much a work in progress, so these instructions are subject to -change. - -As of now, Jex is a glorified shell script that automates a lot of the tedium -in building sidekick, JR, etc. - -The long-term goal is to completely remove any dependency on NPM. NPM comes -with a lot of unfixable security issues that present an unacceptable risk in a -business context, which is the focus of the Vanillae project. +Jex is a work-in-progress package manager developed to solve the specific +packaging needs of the vanillae project. ## Installation +Jex is very much a work in progress, so these instructions are subject to +change, and may not work anymore by the time you are reading this + 0. Install system dependencies ``` tree rsync @@ -58,3 +51,62 @@ COMMANDS: rmpkg PKG rm -r $HOME/.jex/dev/PKG pull pull each dependency into src/jx_include ``` + +## About + +As of now, Jex is a glorified shell script that automates a lot of the tedium +in building sidekick, JR, etc. + +The long-term goal is to completely remove any dependency on NPM. NPM comes +with a lot of unfixable security issues that present an unacceptable risk in a +business context, which is the focus of the Vanillae project. + +This isn't something like yarn where it's the same thing as NPM but it is +prettier or something. Totally different packaging concept. + +### Differences from NPM + + +1. **Minimizing dynamicism** + + The basic assumption of NPM is that everything works all the time, and + because that isn't true, nothing ever works and everything is always + broken. The basic assumption of Jex is that nothing ever works and + everything is always broken, and because that's true, everything works all + the time, sometimes. + + Concretely, this means that you have to do all dependency management + manually. If you are trying to build package `A` and it depends on packages + `B`, `C`, and `D`, then you have to go find packages `B`, `C`, and `D`, + build them and then go back and build package `A`. + + Again, the assumption (objectively true) is that everything is always + broken. So on the off chance that something works by happenstance, Jex's + strategy is to give it the Ted Williams treatment and never touch it ever + again. + + There's an implicit assumption here that the total volume of JavaScript + code is fairly small. Manual dependency management is not feasible if your + project has 11,000 dependencies, requires 18 different packages called + "babel" just to build, and "minifies" to a 20kb opaque blob. As a + guideline, if the number of external package dependencies grows large + enough that a single developer cannot manage them manually, then, (over + time) the primary activity of said developer becomes trying to get all the + different packages to play nicely together. + + In other words, manual dependency management is inescapable. Jex is simply + honest about that fact and prevents you from digging yourself into a hole. + +2. **Node is bad** + + The next departure from NPM is that we don't care at all about the node + runtime. JavaScript was invented by Satan as a joke. Using JavaScript at + all for any reason is a terrible idea. It is an especially terrible idea + to write any code in JavaScript that does not absolutely have to be written + in JavaScript. + + All that is to say, whenever we write JavaScript code, the assumption is + that the code will be run in a browser and only in a browser. + + We are never writing generic libraries that could either run in the browser + or run in the node runtime.