From 7458536bd6aa5d46fa15657c0005fb32f8cdec37 Mon Sep 17 00:00:00 2001 From: Teo Stocco Date: Sun, 30 Jun 2024 13:51:13 +0200 Subject: [PATCH] feat: add intro (#86) * feat: add intro * feat: update pr template * fix: nightly CI issue * refactor: add arm64 darwin/macos nightly jobs * Update nightly.yml --------- Co-authored-by: Yohe-Am <56622350+Yohe-Am@users.noreply.github.com> --- .github/pull_request_template.md | 20 +++--- README.md | 71 +++++++++++-------- ghjk.drawio.svg | 115 +++++++++++++++++++++++++++++++ 3 files changed, 166 insertions(+), 40 deletions(-) create mode 100644 ghjk.drawio.svg diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 78c73a8c..a8ff9b25 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,25 +1,25 @@ -### Describe your change + - +- -### Motivation and context + - +- -### Migration notes + - +#### Migration notes -### Checklist +... -- [ ] The change come with new or modified tests +- [ ] The change comes with new or modified tests - [ ] Hard-to-understand functions have explanatory comments - [ ] End-user documentation is updated to reflect the change diff --git a/README.md b/README.md index 53f84081..8218bb74 100644 --- a/README.md +++ b/README.md @@ -1,14 +1,22 @@ # ghjk -ghjk /jk/ is a programmable runtime manager. +ghjk /gk/ is a programmable runtime manager and an attempt at a successor for [asdf](https://github.com/asdf-vm/asdf). -> Ghjk is part of the +> ghjk is part of the > [Metatype ecosystem](https://github.com/metatypedev/metatype). Consider > checking out how this component integrates with the whole ecosystem and browse > the > [documentation](https://metatype.dev?utm_source=github&utm_medium=readme&utm_campaign=ghjk) > to see more examples. +## Introduction + +ghjk offers a unified abstraction to manage package managers (e.g. cargo, pnpm, poetry), languages runtimes (e.g. nightly rust, node@18, python@latest) and developer tools (e.g. pre-commit, eslint, protoc). It enables you to define a consistent environment across your dev environments, CI/CD pipelines and containers keeping everything well-defined in your repo and providing a great DX. + +ghjk was designed to be an intermediate alternative between [Earthly](https://github.com/earthly/earthly)/[Dagger](https://github.com/dagger/dagger) (lighter and more flexible) and complex building tools like [Bazel](https://github.com/bazelbuild/bazel/)/[Nix-based devenv](https://github.com/cachix/devenv) (simpler and more extensible). This makes it especially convenient for mono-repos and long-lived projects. See [Metatype](https://github.com/metatypedev/metatype) and its [ghjkfile](https://github.com/metatypedev/metatype/blob/main/ghjk.ts) for a real world example. + +![](./ghjk.drawio.svg) + ## Features - Soft-reproducable developer environments. @@ -71,24 +79,22 @@ ghjk.install(ports.rust()); // the previous block is equivalent to ghjk.env("main", { - installs: [ - ports.protoc(), - ports.rust(), - ], + installs: [ports.protoc(), ports.rust()], }); -ghjk.env("dev", { - // by default, all envs are additively based on `main` - // pass false here to make env independent. - // or pass name(s) of another env to base on top of - inherit: false, - // envs can specify posix env vars - vars: { CARGO_TARGET_DIR: "my_target" }, - installs: [ - ports.cargobi({ crateName: "cargo-insta" }), - ports.act(), - ], -}) +ghjk + .env("dev", { + // by default, all envs are additively based on `main` + // pass false here to make env independent. + // or pass name(s) of another env to base on top of + inherit: false, + // envs can specify posix env vars + vars: { CARGO_TARGET_DIR: "my_target" }, + installs: [ + ports.cargobi({ crateName: "cargo-insta" }), + ports.act(), + ], + }) // use env hooks to run code on activation/deactivation .onEnter(ghjk.task(($) => $`echo dev activated`)) .onExit(ghjk.task(($) => $`echo dev de-activated`)); @@ -98,18 +104,11 @@ ghjk.env({ desc: "for Dockerfile usage", // NOTE: env references are order-independent inherit: "ci", - installs: [ - ports.cargobi({ crateName: "cargo-chef" }), - ports.zstd(), - ], + installs: [ports.cargobi({ crateName: "cargo-chef" }), ports.zstd()], }); // builder syntax is also availaible -ghjk.env("ci") - .var("CI", "1") - .install( - ports.opentofu_ghrel(), - ); +ghjk.env("ci").var("CI", "1").install(ports.opentofu_ghrel()); // each task describes it's own env as well ghjk.task({ @@ -154,9 +153,21 @@ Any malicious third-party module your ghjkfile imports will thus be able to acce // evil.ts import { env, task } from "https://.../ghjk/hack.ts"; -env("main") - // lol - .onEnter(task($ => $`rm -rf --no-preserve-root`); +env("trueBase").install(ports.act(), ports.pipi({ packageName: "ruff" })); + +env("test").vars({ DEBUG: 1 }); + +// `stdSecureConfig` is a quick way to make an up to spec `secureConfig`. +export const secureConfig = stdSecureConfig({ + defaultBaseEnv: "trueBase", + defaultEnv: "test", + // by default, nodejs, python and other runtime + // ports are not allowed to be used + // during the build process of other ports. + // Disable this security measure here. + // (More security features inbound!.) + enableRuntimes: true, +}); ``` To prevent this scenario, the exports from `hack.ts` inspect the call stack and panic if they detect more than one module using them. diff --git a/ghjk.drawio.svg b/ghjk.drawio.svg new file mode 100644 index 00000000..a83ca6e0 --- /dev/null +++ b/ghjk.drawio.svg @@ -0,0 +1,115 @@ + + + + + + + +
+
+
+ your application code +
+
+
+ + + your application code + + + + + + + +
+
+
+ development ecosystems (Rust, Node, PHP, Python, etc.) +
+
+
+ + + development ecosystems (Rust, Node, PHP, Python, etc.) + + + + + + + +
+
+
+ ghjk +
+
+
+ + + ghjk + + + + + + + +
+
+
+ dev environments +
+
+
+ + + dev environments + + + + + + + +
+
+
+ CI/CD pipelines +
+
+
+ + + CI/CD pipelines + + + + + + + +
+
+
+ containers +
+
+
+ + + containers + + + + + + + + + Text is not SVG - cannot display + + + +