Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Attempted reorganisation/ rewrite #18

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

Attempted reorganisation/ rewrite #18

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
214 changes: 127 additions & 87 deletions docs/installation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <PATH_TO_ARCHETYPE_BIN>
$ 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.