ivabus/docs
1
0
Fork 0
mirror of https://github.com/ivabus/docs synced 2024-11-21 23:55:06 +03:00
Code Issues Projects Releases Packages Wiki Activity Actions

.some(.md)

Browse source
This commit is contained in:
Max Howell 2023-03-14 09:45:24 -04:00
parent dabeae1634
commit c8e90f335e
No known key found for this signature in database
GPG key ID: 741BB84EF5BB9EEC
18 changed files with 741 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

1
.gitbook.yaml Normal file
View file

@ -0,0 +1 @@
root: ./docs/

7
README.md Normal file
View file

@ -0,0 +1,7 @@
# tea/docs
This documentation is processed by [gitbook.com] and published to
[docs.tea.xyz].
[gitbook.com]: https://gitbook.com
[docs.tea.xyz]: https://docs.tea.xyz

122
docs/FAQ.md Normal file
View file

@ -0,0 +1,122 @@
## How do I update?
```sh
$ tea --sync
# ^^ updates the pantries, and any packages in the virtual-environment
$ tea --sync +deno.land
# ^^ updates specific packages
$ sh <(curl tea.xyz) --sync
# ^^ updates `tea` as well
```
## How do I view what is stowed?
```sh
open $(tea --prefix)
```
We hope to improve this UX very soon.
## I need a tool in `PATH` (aka `brew install`)
Symlinks to `tea` automatically invoke their namesake:
```sh
$ ln -s $(which tea) /usr/local/bin/bun
$ bun --version
tea: installing bun…
bun 0.4.0
# you can version tools this way too
$ ln -s $(which tea) /usr/local/bin/bun~0.3
$ bun~0.3 --version
tea: installing bun=0.3.0
bun 0.3.0
# if you prefer you can symlink with a `tea+` or `tea_` prefix
$ ln -s $(which tea) /usr/local/bin/tea+node
$ tea+node --version
v19.3.0
```
{% hint style="warning" %}
This doesn’t work on Linux; you’ll need to use hard-links. \
This is a platform limitation we cannot work around 😞
{% endhint %}
## How do I use tea with editors like VSCode?
We intend to make a VSCode extension that automatically fetches the
environment for the active workspace. In the meantime, add tools to your `PATH`
as described in the above FAQ.
## What are these `^`, `~`, etc. symbols?
tea adheres to [semantic versioning](https://semver.org), and uses
[`semver`](https://github.com/npm/node-semver#versions) for parsing versions.
## How do I find available packages?
We list all packages at [tea.xyz](https://tea.xyz/+/).
Or `open ~/.tea/tea.xyz/var/pantry`.
We hope to improve this UX very soon, too.
## Will you support platform `foo`?
We want to support *all* platforms.
Start a [discussion] and let’s talk about how to move forward with that.
## What happened to executable markdown?
We may revisit it, but we realized quickly that because tea makes it
so trivial to use anything from the open source ecosystem, it also makes it trivial
for you as a developer to use [`xc`]†, `make` or [`just`] or any of the
myriad of other tools that are tightly scoped to the initial goals of
executable markdown.
> † xc actually *is* a more mature implementation of executable markdown and
> we think you should definitely check it out.
[`xc`]: https://github.com/joerdav/xc
[`just`]: https://just.systems
## What are you doing to my computer?
We install compartmentalized packages to `~/.tea`.
We then suggest you add our one-liner to your shell `.rc` and a symlink
for `/usr/local/bin/tea`.
We might not have installed tea, if you used `sh <(curl tea.xyz) foo` and tea
wasn’t already installed, then we only fetched any packages, including
tea, temporarily.
## Packaging up tea packages with your `.app`, etc.
Our packages are relocatable by default. Just keep the directory structure the
same. And ofc. you are licensed to do so (by us! each package has its own
license!). Honestly we think you should
absolutely bundle and deploy tea’s prefix with your software. We designed it
so that it would be easier for you to do this than anything that has come
before.
## I thought you were decentralized and web3 and shit
tea is creating new technologies that will change how open source is funded.
tea/cli is an essential part of that endeavor and is released
prior to our protocol in order to bootstrap our holistic vision.
We don’t subscribe to any particular “web” at tea.xyz, our blockchain
component will be an implementation detail that you won’t need to think about
(but we think you will want to).
Check out our [white paper] for more information.
# I have another question
Start a [discussion] and we’ll get back to you.
[discussion]: https://github.com/orgs/teaxyz/discussions
[white paper]: https://github.com/teaxyz/white-paper

24
docs/README.md Normal file
View file

@ -0,0 +1,24 @@
`tea` is the next-generation, cross-platform package manager from the creator
of [`brew`].
# Getting Started
| <p>​<a href="get-started/install-tea.md/">Quickstart</a><br>Get started fast with our installer</p> | <p><a href="get-started/without-installer.md">Without the Installer</a><br>`tea`’s a standalone binary download</p> |
| ----- | ----- |
| <p>​<a href="using-tea/">Using `tea`</a><br>A guide to the simple, yet powerful `tea`/cli</p> |
# Features
| <p>​<a href="magic.md">Magic</a><br>Put the entire open source ecosystem at your fingertips</p> | <p><a href="using-tea/developer-environments.md">Developer Environments</a><br>Thin containers for work projects</p> | <p>​<a href="using-tea/tea-scripts.md">`tea` Scripts</a><br>Giving scripts more than just `bash` |
| ----- | ----- | ----- |
# Support
We appreciate your using `tea` and would love to help you solve any problems
you may be having.
* [github.com/orgs/teaxyz/discussions](https://github.com/orgs/teaxyz/discussions)
* [discord.tea.xyz](https://discord.tea.xyz)
[`brew`]: https://brew.sh

31
docs/SUMMARY.md Normal file
View file

@ -0,0 +1,31 @@
‌# Summary​
* [Contents](README.md)
## Getting Started
​
* [Installing `tea`](get-started/install-tea.md)
* [Without the Installer](get-started/without-installer.md)
* [Using tea](using-tea/README.md)
## Features
* [Magic](magic.md)
* [Using `tea` without Magic](using-tea/without-magic.md)
* [Developer Environments](using-tea/developer-environments.md)
* [`tea` Scripts](using-tea/tea-scripts.md)
## Packaging
* [The Pantry](packaging/README.md)
​
## Appendix
​
* [FAQ](FAQ.md)
* [Uninstalling `tea`](appendix/uninstall-tea.md)
* [GitHub Actions](appendix/github-actions.md)
* [The `tea` One-Liner](using-tea/the-tea-one-liner.md)
* [Troubleshooting](troubleshooting.md)
* [Suffix](appendix.md)

58
docs/appendix.md Normal file
View file

@ -0,0 +1,58 @@
# A Brief Diatribe
Every programming language, every build system, every compiler, web server, database and email client seem to gravitate towards adding infinite features and complexity so that their users can do ever more and more.
This is contrary to the UNIX philosophy: tools should do one thing and —by being tight and focused— do it damn well. If they are composable and flexible then they can be combined, piped and leveraged into a larger, more capable toolbox. The Internet is built with this toolbox.
Nowadays every programming language reimplements the same set of libraries and tools because using a well-maintained, mature and portable library that lives higher up the stack adds too much complexity. This extends the adolescence of new languages, results in no single language even becoming truly state of the art and leads to degrees of duplication that make the open source ecosystem fragile. This is to the detriment of all software, everywhere.
tea removes this complexity and adds some much needed robustness for the good of the entire open source ecosystem, the larger Internet and the whole world of software.
# What is tea?
tea is not a package manager.
*tea is unified packaging infrastructure*.
From the creator of [`brew`], tea is a standalone, binary download for all
platforms that puts the entire open
source ecosystem at your fingertips. Casually and effortlessly use the latest
and greatest or the oldest and most mature from any layer of any stack. Break
down the silos between programming communities, throw together scripts that
use entirely separate tools and languages and share them with the world with
a simple one-liner.
All you need is `tea`.
> tea is pre v1. This means there may still be some rough edges in day to day use.
> It also means that you should absolutely get involved. This is the key and
> golden time when getting involved is both easy and hugely fun. We look
> forward to meeting you 👊
# Our Goals
- To create incredible tooling: the base of every developer’s stack.
- To cater to our users, not ourselves.
- To take open source to the next level by funding the unpaid maintainers who thanklessly create the stack that powers the Internet.
# Philosophy
* Be non‑intrusive
> don’t interfere with our users’ systems or habits
* Be “just works”
> our users have better things to do than fix us
* Error messages must be excellent
> trust that if it comes to it, our users can fix things provided we give
> them a helping hand
* Be intuitive
> being clever is good—but don’t be so clever nobody gets it
* Resist complexity
> rethink the problem until a simpler solution emerges
* Be fast
> we are in the way of our users’ real work, don’t make them wait
[`brew`]: https://brew.sh

25
docs/appendix/github-actions.md Normal file
View file

@ -0,0 +1,25 @@
You can easily use `tea` in GitHub Actions:
```yaml
- uses: teaxyz/setup@v0
```
* Our action installs your dependencies and makes them and their environments
available for the rest of the run.
* Our action has no dependencies and will
work in very slim docker containers.
See its GitHub for usage information
[github.com/teaxyz/setup](https://github.com/teaxyz/setup).
## Other CI Services
```sh
sh <(curl https://tea.xyz) --yes
set -a
tea -SE
```
Will export the environment for your developer environment.

31
docs/appendix/uninstall-tea.md Normal file
View file

@ -0,0 +1,31 @@
# Uninstalling `tea`
You can delete `~/.tea` or if you customized tea’s prefix, that directory.
```sh
rm -rf ~/.tea
```
Remove the one liner in your `~/.shellrc`; one of:
* `~/.zshrc`
* `~/.bashrc`
* `~/.config/fish/config.fish`
* etc.
That’s it!
{% hint style="warning" %}
## Caveats
Though not a problem unique to `tea` you should note that tools installed with
`tea` may have polluted your system during use. Check directories like:
* `~/.local`
* `~/.gem`
* `~/.npm`
* `~/.node`
* etc.
{% endhint %}

57
docs/get-started/install-tea.md Normal file
View file

@ -0,0 +1,57 @@
# Getting Started with the Installer
The easiest way to install tea is with our installer:
```sh
sh <(curl https://tea.xyz)
```
The script installs to `~/.tea` and sets up magic (we ask politely first).
{% hint style="info" %}
### Want to Read the Sources for that Script First?
[https://github.com/teaxyz/setup/blob/main/install.sh]
{% endhint %}
## What Happens
* Firstly we confirm you’re cool before we do *anything*
* If so we install tea to `~/.tea`
* If not we exit with failure
* We then ask if you want [magic](../using-tea/with-magic.md)
* If so we add one line to your `~/.shellrc`
* If not we exit successfully
<details><summary><code>`preview.gif`</code></summary>
![charm.sh/vhs recording](https://teaxyz.github.io/setup/sample.gif)
</details>
## It’s Not Just an Installer
If you run it again, it’ll update `tea`.
### That’s Not All
The tea one-liner can also be used to provide your users a temporary sandbox
for your projects. They can use the power of tea to try out your project
without installing tea or your project.
{% hint style="success" %}
See [The `tea` One-Liner](/using-tea/the-tea-one-liner.md) for more details
{% endhint %}
## Linux Caveats
On Linux you may need some pre-requisite packages from your system packager.
This is a temporary situation that we are fixing.
We are keeping a list of pre-reqs in [this script].
[this script]: https://github.com/teaxyz/setup/blob/main/install-pre-reqs.sh
[https://github.com/teaxyz/setup/blob/main/install.sh]: https://github.com/teaxyz/setup/blob/main/install.sh

50
docs/get-started/without-installer.md Normal file
View file

@ -0,0 +1,50 @@
# Installing `tea` Without the Installer
`tea` is a standalone binary and you can prove it:
```sh
$ curl -Lo tea https://tea.xyz/$(uname)/$(uname -m)
$ chmod u+x ./tea
$ echo '# tea *really is* a standalone binary' | ./tea --sync glow -
tea: installing charm.sh/glow
# `tea --sync` updates pkgs, but you have to call it *at least once*
# our installer does this for you normally
```
{% hint style="warning" %}
`tea` stows packages in `~/.tea` and thus the above will do that!
{% endhint %}
## A Fancy One-Liner
Here’s a one-liner that downloads `tea`, makes it executable and puts it in
`/usr/local/bin`:
```sh
sudo install -m 755 \
<(curl --compressed -LSsf https://tea.xyz/$(uname)/$(uname -m)) \
/usr/local/bin/tea
```
## Via [Homebrew](https://brew.sh)
We love `brew` (`tea`’s its spiritual successor) so you can use our tap:
```sh
brew install teaxyz/pkgs/tea-cli
```
## Via Docker
```sh
docker run --rm -it teaxyz/cli
```
{% hint style="info" %}
The Docker image is built nightly: [https://github.com/teaxyz/infuser]
{% endhint %}
[Docker]: https://docker.com
[https://github.com/teaxyz/infuser]: https://github.com/teaxyz/infuser

97
docs/magic.md Normal file
View file

@ -0,0 +1,97 @@
# Magic
Our magic puts the entire open source ecosystem at your fingertips.
Our installer enables it by adding some hooks to your shell:
* A hook when changing directory that sets up project environments
* Environments are just shell environment variables
* A hook for the “command not found” scenario that installs that command
before running it
{% hint style="info" %}
Magic is entirely optional, tea is still entirely usable without it.
{% endhint %}
{% hint style="warning" %}
Our “command not found” magic only works at a terminal prompt. Thus eg.
VSCode won’t magically find `deno`. Shell scripts won’t automatically
install tools they try to run. This is intentional. *Magic should not lead
to anarchy*.
{% endhint %}
Our magic means that tea packages are not generally accessible from the rest
of the system.
```sh
$ which bun
bun not found
$ tea --dry-run bun --version
imagined: bun.sh^0.4
~/.tea/bun.sh/v0.4.0/bin/bun --version
$ bun --version
tea: installing bun.sh^0.4
0.4.0
$ which bun
bun not found
# `bun` is not in your `PATH`
# ∵ tea doesn’t install packages
# ∴ using tea doesn’t compromise your system’s integrity
$ tea bun --version
0.4.0
# ^^ the same as `bun --version` but without magic
```
All packages are installed, segregated and encapsulated in `~/.tea` for other
parts of your system to access them you may have to make them accessible using
`tea +pkg` syntax.
## Symlink Magic
Symlinks to tea are resolved to that tool. Eg:
```sh
$ ln -s tea node
$ node
Welcome to Node 16.7.0
>
```
We support appending [semver](semver.org) ranges:
```sh
$ ln -s tea node^14
$ node
Welcome to Node 14.2.0
> ^D
$ ln -s tea node~16.6
$ node
Welcome to Node 16.6.1
>
```
## Using Magic in Shell Scripts
Our magic is not automatically added to scripts, but you can manually add it:
```sh
source <(tea --magic=bash)
# ^^ you have to specify which shell tho
```
And of course you can also use our one-liner:
```sh
source <(curl tea.xyz | sh -s -- --magic=bash)
```
Thus you can make a script that can effortlessly use any tool from the open
source ecosystem. If they have tea installed it uses their installation, if
not it installs everything (including tea itself) to a temporary sandbox
that’s gone when the script completes.

25
docs/packaging/README.md Normal file
View file

@ -0,0 +1,25 @@
# Packaging
There’s millions of open source projects and `tea` needs your help to package
them up!
{% hint style="info" %}
Visit the [https://github.com/teaxyz/pantry] for the full documentation.
{% endhint %}
Our package listing can be viewed at our homepage: [tea.xyz/+/](https://tea.xyz/+/)
# Packagers Who Care
You trust us to just work and make your workflows happen.
We take this job seriously and we go the extra mile on a per-package basis,
eg. our `git` ignores `.DS_Store` files by default, and our RubyGems defaults to
user-installs and ensures gems are in `PATH`. Also we insist our packages
are relocatable, which is why we can install in your home directory (but this
also means you could pick up the whole `~/.tea` directory and bundle it with
your app.) We also begin packaging new releases almost immediately as soon as
they go live using various automations.
[https://github.com/teaxyz/pantry]: https://github.com/teaxyz/pantry

20
docs/troubleshooting.md Normal file
View file

@ -0,0 +1,20 @@
# Troubleshooting
## `env: tea: No such file or directory`
If you got this error message, you need to install tea:
`sh <(curl -Ssf https://tea.xyz)`.
## Changing directory takes a long time sometimes
This is a known and insidious bug. Please open a [ticket] and report it to us.
tea’s magic should never significantly slow down directory changes.
## Unquarantining on macOS
If the macOS GateKeeper says no, try this:
```sh
$ xattr -d com.apple.quarantine ./tea
```

0
docs/using-tea/README.md Normal file
View file

114
docs/using-tea/developer-environments.md Normal file
View file

@ -0,0 +1,114 @@
# Developer Environments
Every project you work on needs different tools with different versions.
Installing those tools globally *makes no sense* and could even cause subtle
bugs during dev.
tea can determine the tools a project directory needs based on the files it
finds. With our shell magic just step into the project directory
and type commands; tea automatically fetches the specific versions those
projects need and runs them.
We try to be as clever as possible, eg. we parse the node version out of
a GitHub Action’s `action.yml`. If we see a `.node-version` file, we add that
version of node to the environment. We want to support everything that makes
sense (your PRs are *very* welcome!)
Where there isn’t a convention for specifying tool versions, you can add
YAML front matter to its configuration file. For example, if we’re
talking a python poetry project, then you can specify your python version by
adding YAML front matter to its `pyproject.toml`:
```sh
$ cat <<EoYAML >> pyproject.toml
# ---
# dependencies:
# python.org: ^3.11.3
# ---
EoYAML
```
If your poetry project needs other non pypa dependencies (like a c compiler)
then you can add them there too (eg. `llvm.org`, our deps are always named
after project homepages because then you just google it and there’s no
ambiguity).
If you prefer we also support extracting your deps from a markdown table
under a `# Dependencies` section in your `README.md`:
```sh
$ cat <<EOF >>my-project/README.md
# Dependencies
| Project | Version |
| ---------- | ------- |
| go.dev | ^1 |
EOF
```
Using your `README` is *kinda* neat; it makes this data both machine and human
readable.
Finally, you can just use `tea.yaml` (or `.tea.yaml`) if you like.
<details><summary><i>PSA:</i> Stop using Docker</summary><br>
Docker is great for deployment and cross compilation, but… let’s face it: it
sucks for dev.
*Docker stifles builders*.
It constricts you; you’re immalleable; tech marches onwards but your docker
container remains immobile. *Nobody knows how to use `docker`*. Once that
`Dockerfile` is set up, nobody dares touch it.
And let’s face it, getting your personal dev and debug tools working inside
that image is incredibly frustrating. Why limit your potential?
Keep deploying with Docker, but use tea to develop.
Then when you do deploy you may as well install those deps with tea.
Frankly, tea is properly versioned (unlike system packagers) so with tea your
deployments actually remain *more* stable.
</details>
## Caveats
We still need to do a bit of work here. We don’t install any packages when
you step into a directory as that would violate the principle of least
surprise. But this may mean the full environment doesn’t work initially.
You can fix this with a `tea -SE && cd .`. We’re working on improving this.
## Supplementing the Environment
There are all sorts of variables a developer needs when working on a project
and tea aims to make them available to you. Thus we provide `SRCROOT` and
`VERSION`‡ in addition to everything else required to make your devenv
function. To see the full environment for your project run `tea -En` or simply
`env`.
> ‡ extracted from the `README.md` or `VERSION` files.
## Supported Files
* `package.json`
* `deno.json`, `deno.jsonc`
* `pyproject.toml`, `pipfile`, `requirements.txt`
* `go.mod`
* `VERSION`
* `.node-version`
* `cargo.toml`
* `Gemfile`
* `tea.yaml`, `.tea.yml`
* `README.md`
* `.envrc`
## I added YAML front matter and it doesn’t work; what now?
* After changing any files you need to do a `cd .` to reload the environment.
* While debugging you can do `tea -E` to see if we’re picking up your changes.
* If it still doesn’t work open a [ticket]. This is either a bug or we don’t
support your toolset yet.
[ticket]: https://github.com/teaxyz/cli/issues/new

6
docs/using-tea/tea-scripts.md Normal file
View file

@ -0,0 +1,6 @@
# `tea` Scripts
* `tea` reads the shebang of a script and installs that interpreter
* If no shebang the extension is used
* Any YAML Front Matter will be read in addition allowing further packages to
be installed for that script

36
docs/using-tea/the-tea-one-liner.md Normal file
View file

@ -0,0 +1,36 @@
## As a Proxy
Arguments passed to the one-liner act as though they were passed to `tea`
itself.
```sh
$ sh <(curl tea.xyz) bun run start
bun: start…
```
{% hint style="info" %}
Notably, if `tea` is not installed the one-liner *does not install `tea`*.
Instead it stows and packages in a temporary sandbox and runs them there.
This may be useful for your getting started guides so users can try your tools
out without consequences.
{% endhint %}
## As an Updater
The installer will update tea if it’s already installed.
## All Options
```sh
sh <(curl tea.xyz) --prefix /opt/tea
# ^^ installs tea to /opt/tea
sh <(curl tea.xyz) --version 0.24.10
# ^^ installs a specific version of tea/cli
sh <(curl tea.xyz) --yes
# assumes yes for all questions (for headless environments)
```

37
docs/using-tea/without-magic.md Normal file
View file

@ -0,0 +1,37 @@
## Using `tea` Without Magic
Simply prefix everything with `tea`, eg. `tea npm start`.
## Using Developer Environments Without Magic
Simply prefix commands with `tea -E`, eg. `tea -E npm start`.
## Injecting Packages without Using Magic
Our `+pkg` syntax *injects* packages into an environment, the commands are
then run in that environment.
```sh
# a script that needs `convert`
$ tea +imagemagick.org my-script.sh
# a VHS script that needs `wget`
$ tea +gnu.org/wget vhs demo.tape
# if tea doesn’t provide the package, it passes the args through to your system
$ tea +neovim.io which nvim
~/.tea/neovim.io/v0.8.2/bin/nvim
# in fact, `tea` is like an “env++”: just like `env` our purpose is to
# construct environments. Our `++` is: we also fetch packages. Thus, if you
# don’t specify what we should do with the environment, we dump it:
$ tea +zlib.net
MANPATH=/Users/mxl/.tea/zlib.net/v1.2.13/share/man:/usr/share/man
PKG_CONFIG_PATH=/Users/mxl/.tea/zlib.net/v1.2.13/lib/pkgconfig
LIBRARY_PATH=/Users/mxl/.tea/zlib.net/v1.2.13/lib
CPATH=/Users/mxl/.tea/zlib.net/v1.2.13/include
XDG_DATA_DIRS=/Users/mxl/.tea/zlib.net/v1.2.13/share
```