diff --git a/docs/installation.md b/docs/installation.md index 15ef51f8..e9d7eebd 100644 --- a/docs/installation.md +++ b/docs/installation.md @@ -1,137 +1,177 @@ -# Installation +# Installation and Setup -## Completium CLI +## Recommended setup +The recommended setup for developing Archetype smart contracts consists of four elements: -[Completium CLI](/docs/cli/introduction) is the command line utility to install Archetype compiler and manage contracts (deploy, call). +1. Visual Studio Code and Archetype extension +2. Completium-CLI command line utility +3. Archetype compiler +4. Testing framework -Install it and initialize its configuration: -```completium +A presentation of a suggested technical stack for a decentralised front-end application is presented in the DApps section. + +## 1. Install VS Code and extension + +Visual studio code is a free IDE. [Install](https://code.visualstudio.com/) and open it. + +The [Archetype language support for visual code](https://marketplace.visualstudio.com/items?itemName=edukera.archetype) extension can be downloaded from the extensions tab in VS code (search for archetype). + +The extension provides: + +- syntax highlighting +- inlined errors (syntax, types, ...) +- compiler command (`Archetype: Generate Michelson`) + +Details about how to setup the vscode extension are covered below. + +## 2. Install Completium CLI + +[Completium-CLI](https://archetype-lang.org/docs/cli/introduction) is a command line utility which allows users to: + - interact with tezos accounts and contracts on the "real" blockchain (mainnet) or a developer chain (e.g ghostnet) + - manage mockup and sandbox environments + - generate bindings to interface between Archetype and Typescript + - install and manage the Archetype compiler + +Install Completium CLI with the following commands: + +``` $ npm install -g @completium/completium-cli $ completium-cli init ``` -### JS -By default, Completium-CLI uses the [JS version](https://www.npmjs.com/package/@completium/archetype) of Archetype compiler. +Always run `completium-cli init` after updating or reinstalling Completium CLI to initialize its configuration. -:::caution -The JS version of Archetype compiler fails when the contract reaches a certain size. It is recommended to use the docker container or the binary version of the compiler. -::: +## 3. Install Archetype compiler -Switch back to JS compiler from other compiler modes (docker, binary) with: -```completium -completium-cli set mode archetype js -``` -### Docker +To install Archetype really means to install the Archetype compiler. This compiler converts the your Archetype code into the low level [Michelson language](https://www.michelson.org/) that is common to all tezos contracts deployed on chain. + +### Default compiler option: JS + +By default, a javascript version of the compiler is installed with `completium-cli`. However, this default version of the compiler fails when a contract reaches a certain size. -Install Docker container of Archetype compiler with: -```completium +If you are new to Archetype and want to get started quickly, or only wish to write and deploy small contracts, you can safely move on to the [next section](https://archetype-lang.org/docs/installation#testing-framework). You can return to these docs if you hit the contract size limit in future. We recommend you complete your setup by switching to the docker compiler now, if time permits. It should take no more than 5-10 minutes. + +### Recommended compiler option: Docker + +Running the binary compiler in a docker container is recommended for most users. Installation is fast. Updates are easy. + +1. Install and open [docker desktop](https://www.docker.com/products/docker-desktop/). Docker *must be running* for the following command, and indeed the compiler, to work. +2. Install the [latest container](https://hub.docker.com/r/completium/archetype) of Archetype compiler with `docker pull completium/archetype:latest` +3. In the terminal, run `completium-cli switch mode archetype` and select `docker` from the menu. +4. In VS Code Settings, set `Archetype: Archetype Mode` to `docker` + +You should now have a working setup. *Remember that docker-desktop must be running for the compiler to work under this setup.* You can update your version of Archetype with: +``` completium-cli install archetype +completium-cli init ``` -This requires [docker](https://www.docker.com/products/docker-desktop/) to be installed, and will download the [latest version](https://hub.docker.com/r/completium/archetype) of Archetype compiler . +### Alternate compiler option: native binary compiler + +A native binary compiler is available for the following platforms: + +- Linux (x64) +- Macos (arm64) + +#### Installation +There are 3 ways to install the binary compiler natively: -:::info -This command runs docker command `docker pull completium/archetype:latest`, hence it also *updates* to the latest version of Archetype compiler. -::: +##### Option 1: Download the binary compiler from the github [release page](https://github.com/edukera/archetype-lang/releases/latest). -### Binary +##### Option 2: Install with [opam](https://opam.ocaml.org/): ` opam install archetype`. -It is possible to configure Completium CLI to use a [binary version](/docs/installation#install-binary) of the Archetype compiler. +##### Option 3: Install from source: + +Require [Opam](https://opam.ocaml.org/) to be installed. Fork the [archetype-lang repository](https://github.com/completium/archetype-lang/). Replace the link in following snippet with a link to your fork of the repository. -Switch to binary compiler: -```completium -$ completium-cli set binary path archetype -$ completium-cli set mode archetype binary ``` +git clone https://github.com/your-github-username/archetype-lang.git +cd archetype-lang +make build-deps +eval $(opam env) +``` + +#### After Installation + +1. In the terminal, run `completium-cli switch mode archetype` and select `binary` from the menu. +2. go to VS Code Settings: +- Fill `Archetype: Archetype Bin` with the path of Archetype compiler +- Set `Archetype: Archetype Mode` to `binary` ### Utility commands -It is possible to open a menu to switch archetype install 'mode': -```completium +Switch between Archetype compilers with the following command: + +``` $ completium-cli switch mode archetype -Current archetype mode: binary -? Switch archetype mode … - js -▸ docker - binary +Current archetype mode: binary? +Switch archetype mode … +▸js + docker + binary ``` Select mode with up/down arrows, then press enter. +If you are using VS Code, you will have to change the VS Code setting accordingly. See the installation instructions for the relevant mode. + Print Archetype's install 'mode' with: -```completium -completium-cli show mode archetype -``` -Print current version of Archetype compiler with: -```completium -completium-cli archetype version +``` +completium-cli show mode archetype ``` -## VS code extension +### Updating Completium-Cli and Archetype -It is recommended to develop Archetype contracts with [VS Code](https://code.visualstudio.com) and the [Archetype extension](https://marketplace.visualstudio.com/items?itemName=edukera.archetype). +Always run `completium-cli init` after updating or reinstalling completium-cli to initialize its configuration. -The extension provides: -* syntax highlighting -* inlined errors (syntax, types, ...) -* compiler command (`Archetype: Generate Michelson`) +You can check the currently installed version of the Archetype compiler with: -### JS +``` +completium-cli archetype version +``` -Like Completium CLI, the Archetype extension uses by default the JS version of Archetype compiler. +If you still using the JS version of the compiler, you can update to the latest Archetype version by simply reinstalling completium-cli: -:::caution -The JS version of Archetype compiler fails when the contract reaches a certain size. It is recommended to switch to the docker container or to the binary version of the compiler. -::: +``` +$ npm install -g @completium/completium-cli +$ completium-cli init +``` -### Docker +If you are running the compiler via docker container, you can update Archetype with: -This requires [docker](https://www.docker.com/products/docker-desktop/) to be installed: -1. install the [latest container](https://hub.docker.com/r/completium/archetype) of Archetype compiler with `docker pull completium/archetype:latest` -2. go to VS Code Settings, search for `Archetype: Archetype Mode` and *select* `docker` +``` +completium-cli install archetype +``` -### Binary +Remember to also update Completium-Cli seperately as required. -The process is as follows: -1. [install the binary](/docs/installation#install-binary) version of archetype compiler -2. go to VS Code Settings: - 1. search for `Archetype: Archetype Bin` and *fill* the path of Archetype compiler - 2. search for `Archetype: Archetype Mode` and *select* `binary` +If you are using a native binary compiler, the usual approach is to reinstall or update the binary using the method or tool you installed it with. -## Install Binary -There are 3 ways to install the binary compiler. +## 4.Testing framework -### Download +The final aspect of your Archetype development setup is to create a project with the testing framework in place. -Download the binary compiler from the github [release](https://github.com/edukera/archetype-lang/releases/latest) page. It is available for the following platform: -* Linux (x64) -* Macos (arm64) +The testing framework generally consists of: +- Tests written in [Typescript](https://www.typescriptlang.org/) using a generic testing library such as [Mocha](https://mochajs.org/) or [Jest](https://jestjs.io/) +- Test execution with [Node.js](https://nodejs.org/en/) +- Contract bindings allowing an API between your typescript code and the test contracts. Generated with completium-cli +- A mockup of the tezos chain to simulate interactions between accounts and contracts. Managed with completium-cli +- Completium packages to provide binding types and various utilities -### Opam +A directory with much of this framework already in place can be built with the following commands: -Install with [opam](https://opam.ocaml.org/): -```completium -opam install archetype ``` - -### From source - -Requires [opam](https://opam.ocaml.org/) to be installed: - -```completium -git clone https://github.com/completium/archetype-lang.git -b master -cd archetype-lang -make build-deps -eval $(opam env) -make all +completium-cli create project my-project +cd my-project +npm i ``` -## Check Binary +For a practical guide to this testing framework, you can jump to [Writing Tests](https://archetype-lang.org/docs/tests/writingtests) -In order to check if the binary is working, this following command print the version of archetype: +## What's next? -```bash -_build/default/src/compiler.exe -v -``` +Want to learn by doing? Try this practical introduction to smart contracts and dapps with Archetype: [First DApp](https://completium.com/docs/dapp-first) + +Want a conceptual introduction? Click next to read about the basic building blocks of Archetype.