In this guide we'll go over installation and basic usage to get going.
nodejs v15.x.x or greater # I recommend using nvm # https://github.com/nvm-sh/nvm # example usage: nvm use v15.0.1 # Suggestion to run the entire tutorial install docker
npm install -g @createdreamtech/carti carti --help carti version
Here we will add the default bundles to our global store, this will allow us to create packages from a default base, without downloading the requirements each time.
carti machine install -g --nobundle --nobuild \ https://raw.githubusercontent.com/createdreamtech/carti-default/main/carti-machine-package.json
Here will use the default packages to create a cartesi machine
mkdir carti-example cd carti-example carti machine init cat carti-machine-package.json
Since we aren't adding new packages we can just build the machine without installing missing bundles
carti machine install carti-machine-package.json
Your directory should look like this
. ├── carti-machine-package.json ├── carti_build │ └── bundles │ ├── baenrwia5vqqvdu5chzjqq57tfo45z2txorpnmljeiuwemcibba43noqpvu │ │ ├── carti-meta.json │ │ └── linux-5.5.19-ctsi-2.bin │ ├── baenrwig2hfjzzeqmozb7sws6tyxmyazvuipjp5hxamtllifsokwh73eucy │ │ ├── carti-meta.json │ │ └── rootfs.ext2 │ └── baenrwigwdfweve3apyvwicc2zpmzz6vdhsg62xnmzhauruw6ud4dbbafuq │ ├── carti-meta.json │ └── rom.bin └── machine-config.lua
This outputs by default a mountable build directory that contains all the bundles related to your machine
machine build - allows us to determine what the machine config looks like internally we map to a virtual directory so we can use this in any context we want
cat carti-machine-package.json return { ram = { length = 0x4000000, image_filename = "/opt/carti/packages/baenrwia5vqqvdu5chzjqq57tfo45z2txorpnmljeiuwemcibba43noqpvu/linux-5.5.19-ctsi-2.bin", }, rom = { image_filename = "/opt/carti/packages/baenrwigwdfweve3apyvwicc2zpmzz6vdhsg62xnmzhauruw6ud4dbbafuq/rom.bin", bootargs = "console=hvc0 rootfstype=ext2 root=/dev/mtdblock0 rw quiet mtdparts=flash.0:-(root) -- ls", }, flash_drive = { { start = 0x8000000000000000, length = 0x3c00000, image_filename = "/opt/carti/packages/baenrwig2hfjzzeqmozb7sws6tyxmyazvuipjp5hxamtllifsokwh73eucy/rootfs.ext2", shared = false, }, }, }
Note how image_filename points to /opt/carti/packages this can be changed using carti machine build --dir /some/path
carti machine build --norunscript
carti docker
Outputs some hints on how to run machine . Try the following if you have docker and the playground
docker run -e USER=$(id -u -n) -e UID=$(id -u) -e GID=$(id -g) -e GROUP=$(id -g -n) \ -v$(pwd):/opt/carti -v $(pwd)/carti_build/bundles:/opt/carti/packages \ -it cartesi/playground /bin/bash cd /opt/carti; luapp5.3 run-config.lua machine-config
When you run the run script it also by default creates a stored machine. That machine is generated as cartesi-machine folder in the cwd.
carti machine add boot "echo 'Hello World'"
rm -rf cartesi-machine/ docker run -e USER=$(id -u -n) -e UID=$(id -u) -e GID=$(id -g) -e GROUP=$(id -g -n) \ -v$(pwd):/opt/carti -v $(pwd)/carti_build/bundles:/opt/carti/packages \ -it cartesi/playground /bin/bash cd /opt/carti; luapp5.3 run-config.lua machine-config
I'd recommend checking out the tutorial to do some more intricate things, such as create your own bundle, a bundless flashdrive, and publish a machine