From 0e82c183ec4dac08bf47713b1faffbb1f0fa7dc7 Mon Sep 17 00:00:00 2001 From: Matej Sima Date: Wed, 5 Jun 2019 16:46:00 +0200 Subject: [PATCH 01/10] Update CI config to create & deploy 'next' version of docs --- .gitlab-ci.yml | 48 ++++--- gitlab-pages/docker-compose.yml | 3 + gitlab-pages/website/pages/en/versions.js | 121 ++++++++++++++++++ gitlab-pages/website/removeNext.js | 8 ++ gitlab-pages/website/siteConfig.js | 2 +- .../version-next/api-cli-commands.md | 48 +++++++ .../contributors/big-picture/back-end.md | 19 +++ .../contributors/big-picture/front-end.md | 16 +++ .../contributors/big-picture/middle-end.md | 17 +++ .../contributors/big-picture/overview.md | 17 +++ .../contributors/big-picture/vendors.md | 22 ++++ .../contributing/getting-started.md | 41 ++++++ .../version-next/contributors/origin.md | 11 ++ .../version-next/contributors/philosophy.md | 46 +++++++ .../contributors/road-map/long-term.md | 21 +++ .../contributors/road-map/short-term.md | 21 +++ .../language-basics-entrypoints.md | 45 +++++++ .../version-next/language-basics-functions.md | 23 ++++ .../version-next/language-basics-operators.md | 13 ++ .../version-next/language-basics-variables.md | 19 +++ .../version-next/setup-installation.md | 37 ++++++ .../version-next-sidebars.json | 36 ++++++ gitlab-pages/website/versions.json | 3 + 23 files changed, 615 insertions(+), 22 deletions(-) create mode 100644 gitlab-pages/website/pages/en/versions.js create mode 100644 gitlab-pages/website/removeNext.js create mode 100644 gitlab-pages/website/versioned_docs/version-next/api-cli-commands.md create mode 100644 gitlab-pages/website/versioned_docs/version-next/contributors/big-picture/back-end.md create mode 100644 gitlab-pages/website/versioned_docs/version-next/contributors/big-picture/front-end.md create mode 100644 gitlab-pages/website/versioned_docs/version-next/contributors/big-picture/middle-end.md create mode 100644 gitlab-pages/website/versioned_docs/version-next/contributors/big-picture/overview.md create mode 100644 gitlab-pages/website/versioned_docs/version-next/contributors/big-picture/vendors.md create mode 100644 gitlab-pages/website/versioned_docs/version-next/contributors/contributing/getting-started.md create mode 100644 gitlab-pages/website/versioned_docs/version-next/contributors/origin.md create mode 100644 gitlab-pages/website/versioned_docs/version-next/contributors/philosophy.md create mode 100644 gitlab-pages/website/versioned_docs/version-next/contributors/road-map/long-term.md create mode 100644 gitlab-pages/website/versioned_docs/version-next/contributors/road-map/short-term.md create mode 100644 gitlab-pages/website/versioned_docs/version-next/language-basics-entrypoints.md create mode 100644 gitlab-pages/website/versioned_docs/version-next/language-basics-functions.md create mode 100644 gitlab-pages/website/versioned_docs/version-next/language-basics-operators.md create mode 100644 gitlab-pages/website/versioned_docs/version-next/language-basics-variables.md create mode 100644 gitlab-pages/website/versioned_docs/version-next/setup-installation.md create mode 100644 gitlab-pages/website/versioned_sidebars/version-next-sidebars.json create mode 100644 gitlab-pages/website/versions.json diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 24a63b809..6fc7854ac 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -8,6 +8,23 @@ stages: - build_and_deploy_website - test +.website_build: &website_build + stage: build_and_deploy_website + image: node:8 + before_script: + - cd gitlab-pages/website + - npm install + script: + - rm -rf versioned_docs/version-next + - rm versioned_sidebars/version-next-sidebars.json + - node removeNext.js + - npm run version next + - npm run build + - cd ../.. + - cp -r gitlab-pages/website/build/ligo public + artifacts: + paths: + - public .docker: &docker image: docker:1.11 @@ -43,7 +60,7 @@ stages: - printf '' | ocaml - opam switch -local-dune-job: +.local-dune-job: <<: *before_script stage: test script: @@ -58,7 +75,7 @@ local-dune-job: # paths: # - src/ligo/bin/cli.ml -local-repo-job: +.local-repo-job: <<: *before_script stage: test script: @@ -67,7 +84,7 @@ local-repo-job: #--build-test - opam install -y ligo -remote-repo-job: +.remote-repo-job: <<: *before_script stage: test script: @@ -84,7 +101,7 @@ remote-repo-job: - master # Run a docker build without publishing to the registry -build-current-docker-image: +.build-current-docker-image: stage: build_docker <<: *docker <<: *docker_build @@ -93,7 +110,7 @@ build-current-docker-image: # When a MR/PR is merged to master # take the previous build and publish it to Docker Hub -build-and-publish-latest-docker-image: +.build-and-publish-latest-docker-image: stage: build_and_deploy_docker <<: *docker <<: *docker_build @@ -105,19 +122,8 @@ build-and-publish-latest-docker-image: pages: - stage: build_and_deploy_website - image: node:8 - before_script: - - cd gitlab-pages/website - - npm install - script: - - npm run build - - pwd - - cd ../.. - - pwd - - cp -r gitlab-pages/website/build/ligo public - artifacts: - paths: - - public - only: - - master + <<: *website_build + # only: + # - master + # - dev + diff --git a/gitlab-pages/docker-compose.yml b/gitlab-pages/docker-compose.yml index 6711192ae..79619bae3 100644 --- a/gitlab-pages/docker-compose.yml +++ b/gitlab-pages/docker-compose.yml @@ -13,6 +13,9 @@ services: - ./website/i18n:/app/website/i18n - ./website/pages:/app/website/pages - ./website/static:/app/website/static + - ./website/versioned_sidebars:/app/website/versioned_sidebars + - ./website/versioned_docs:/app/website/versioned_docs - ./website/sidebars.json:/app/website/sidebars.json - ./website/siteConfig.js:/app/website/siteConfig.js + - ./website/versions.json:/app/website/versions.json working_dir: /app/website diff --git a/gitlab-pages/website/pages/en/versions.js b/gitlab-pages/website/pages/en/versions.js new file mode 100644 index 000000000..663a91167 --- /dev/null +++ b/gitlab-pages/website/pages/en/versions.js @@ -0,0 +1,121 @@ +/** + * Copyright (c) 2017-present, Facebook, Inc. + * + * This source code is licensed under the MIT license found in the + * LICENSE file in the root directory of this source tree. + */ + +const React = require('react'); + +const CompLibrary = require('../../core/CompLibrary'); + +const Container = CompLibrary.Container; + +const CWD = process.cwd(); + +const versions = require(`${CWD}/versions.json`); + +function Versions(props) { + const {config: siteConfig} = props; + const latestVersion = versions[0]; + const repoUrl = `https://github.com/${siteConfig.organizationName}/${ + siteConfig.projectName + }`; + return ( +
+ +
+
+

{siteConfig.title} Versions

+
+

New versions of this project are released every so often.

+

Current version (Stable)

+ + + + + + + {/* */} + + +
{latestVersion} + {/* You are supposed to change this href where appropriate + Example: href="/docs(/:language)/:id" */} + + Documentation + + + Source Code + + Release Notes +
+

+ This is the version that is configured automatically when you first + install this project. +

+

Pre-release versions

+ + + + + + + + +
next + {/* You are supposed to change this href where appropriate + Example: href="/docs(/:language)/next/:id" */} + + Documentation + + + Source Code +
+

Other text describing this section.

+

Past Versions

+

Here you can find previous versions of the documentation.

+ + + {versions.map( + version => + version !== latestVersion && ( + + + + + + ), + )} + +
{version} + {/* You are supposed to change this href where appropriate + Example: href="/docs(/:language)/:version/:id" */} + + Documentation + + + + Release Notes + +
+

+ You can find past versions of this project on{' '} + Gitlab. +

+
+ +
+ ); +} + +module.exports = Versions; diff --git a/gitlab-pages/website/removeNext.js b/gitlab-pages/website/removeNext.js new file mode 100644 index 000000000..280bddec5 --- /dev/null +++ b/gitlab-pages/website/removeNext.js @@ -0,0 +1,8 @@ +// This script is used to remove 'next' from the versions.json file in order to re-create in the CI +const versions = require('./versions.json') +const fs = require('fs'); + +const versionsWithoutNext = versions + .filter(version => version !== "next"); + +fs.writeFileSync("./versions.json", JSON.stringify(versionsWithoutNext)); diff --git a/gitlab-pages/website/siteConfig.js b/gitlab-pages/website/siteConfig.js index 3d0a31c00..fd2f70e59 100644 --- a/gitlab-pages/website/siteConfig.js +++ b/gitlab-pages/website/siteConfig.js @@ -159,7 +159,7 @@ const siteConfig = { // You may provide arbitrary config keys to be used as needed by your // template. For example, if you need your repo's URL... - // repoUrl: 'https://github.com/facebook/test-site', + repoUrl: 'https://gitlab.com/ligolang/ligo', }; module.exports = siteConfig; diff --git a/gitlab-pages/website/versioned_docs/version-next/api-cli-commands.md b/gitlab-pages/website/versioned_docs/version-next/api-cli-commands.md new file mode 100644 index 000000000..47b3da3c8 --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-next/api-cli-commands.md @@ -0,0 +1,48 @@ +--- +id: version-next-api-cli-commands +title: CLI Commands +original_id: api-cli-commands +--- + +Contracts written in Ligo can be compiled using the `ligo` executable. + + +## Compiling a contract + +Compile your contract with a specific entry point. + +```zsh +ligo compile-contract SOURCE_FILE [ENTRY_POINT] +``` + +#### Example + +```zsh +ligo compile-contract examples/counter.ligo main +``` + +## Defining the initial storage + +If your contract implements a sophisticated storage, you can compile a Ligo expression into a Michelson value quite easily. + +```zsh +ligo compile-storage SOURCE_FILE ENTRY_POINT EXPRESSION +``` + +#### Example +```zsh +ligo compile-storage examples/counter.ligo main 5 +# Outputs: 5 +``` + +## Invoking the contract with a parameter + +```zsh +ligo compile-parameter SOURCE_FILE ENTRY_POINT EXPRESSION +``` + +#### Example +```zsh +ligo compile-parameter examples/counter.ligo main "Increment(5)" +# Outputs: (Right 5) +``` \ No newline at end of file diff --git a/gitlab-pages/website/versioned_docs/version-next/contributors/big-picture/back-end.md b/gitlab-pages/website/versioned_docs/version-next/contributors/big-picture/back-end.md new file mode 100644 index 000000000..ae36db90d --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-next/contributors/big-picture/back-end.md @@ -0,0 +1,19 @@ +--- +id: version-next-back-end +title: Back End +original_id: back-end +--- + +The Back-End is the part that compiles down to Michelson. Instead of a single compilation step, it is separated in two parts. +## Transpiler and Mini_C +The Transpiler is a function that takes as input the Typed AST, and outputs expressions in a language that is basically a Michelson based on with named variables and first-class-environments. +On the one hand, there are cases in the AST like `E_if_bool` or `E_make_empty_list` that would be directly translated in Michelson like `IF {} {}` or `NIL`. +On the other hand, there are cases in the AST like `E_variable` or `E_environment_select` that specifically target the compiler. +The files of the Transpiler are in `transpiler/`, while those of Mini_c are in `mini_c/`. +## Compiler +The previous LIGO’s compilation to Michelson model was quite complicated. The current one is quite straightforward, where the environment of variables (x -> 12, y -> “foo”) is compiled as Michelson stack (12 :: foo). +It has been simplified for multiple reasons: +Having a simple model reduces its number of points of failure. +Having a simple model makes optimizing it easier. +We submitted a change to the Tezos’ protocol that actually make it more efficient. + diff --git a/gitlab-pages/website/versioned_docs/version-next/contributors/big-picture/front-end.md b/gitlab-pages/website/versioned_docs/version-next/contributors/big-picture/front-end.md new file mode 100644 index 000000000..0664fb486 --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-next/contributors/big-picture/front-end.md @@ -0,0 +1,16 @@ +--- +id: version-next-front-end +title: Front End +original_id: front-end +--- + +The Front-End is the part that deals with all syntactical matters. LIGO supports multiple Front-Ends. Each Front-End is composed of three different parts. +## Parser +A Parser is a function that takes a string of source code and outputs a structured representation of the program. This part usually uses Menhir, a parser generator compatible with OCaml. +Its files are in `parser/parser_name`. +## Concrete Syntax Tree +The CST is the aforementioned structured representation of the program. Is is structurally very close to the source code, and is mostly an intermediary there because manipulating string is not practical. +Its files are in `parser/parser_name`. +## Simplifier +A Simplifier is a function that takes a CST and outputs the corresponding Common AST. This is the actual bridge between a given syntax and LIGO. +Its files are in `simplify/parser_name`. diff --git a/gitlab-pages/website/versioned_docs/version-next/contributors/big-picture/middle-end.md b/gitlab-pages/website/versioned_docs/version-next/contributors/big-picture/middle-end.md new file mode 100644 index 000000000..6e60ba2a2 --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-next/contributors/big-picture/middle-end.md @@ -0,0 +1,17 @@ +--- +id: version-next-middle-end +title: Middle End +original_id: middle-end +--- + +The Middle-End is the core of LIGO. It is also composed of three parts. +## Common AST +The Common AST is the closest thing to what could be called “LIGO lang”. As such, it should be as simple as possible. Collapsing particular cases in more general constructs is encouraged. Documenting it is crucial for people who’ll write new parsers or editor support for Front-end related things. +Its files are in `ast_simplified/`, of interest is the definition of the AST itself in `ast_simplified/types.ml`. +## Type Checker +The Type Checker, among other things, checks that a given AST is valid with regard to type-safety. It also annotates expressions with their types, free-variables and local environments. +As time passes, we want to make the type-system stronger, to encode arbitrarily complex properties in an extensible manner. +Its files are in `typer/`. +## Typed AST +The Typed AST is the result of Type Checker. On top of it, we also want to define/export many features aiming at making building tools on top LIGO as easy as possible. +Its files are in `ast_typed/`, of interest is the definition of the Typed AST itself in `ast_typed/types.ml`. diff --git a/gitlab-pages/website/versioned_docs/version-next/contributors/big-picture/overview.md b/gitlab-pages/website/versioned_docs/version-next/contributors/big-picture/overview.md new file mode 100644 index 000000000..04e5baa50 --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-next/contributors/big-picture/overview.md @@ -0,0 +1,17 @@ +--- +id: version-next-overview +title: Overview +original_id: overview +--- + +After going through the design principles and a few considerations linked to them, getting the Big Picture needs diving in technical matters. + +![LIGO Overview](/img/big-picture-overview.png) + +As shown in the Schema, LIGO’s compiler is separated in roughly 3 separate parts: + +- The Middle End. This is the core of LIGO. It defines its core data-structure (the Common AST), and its type-checking algorithm. + +- The Front End. This is the bridge between a given syntax and the Common AST. + +- The Back End. This is the bridge between the Common AST and a given compilation target. Currently, our only target is Michelson, but we’ll also target Marigold, and if Tezos moves to Web Assembly, Web Assembly. diff --git a/gitlab-pages/website/versioned_docs/version-next/contributors/big-picture/vendors.md b/gitlab-pages/website/versioned_docs/version-next/contributors/big-picture/vendors.md new file mode 100644 index 000000000..ebb116367 --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-next/contributors/big-picture/vendors.md @@ -0,0 +1,22 @@ +--- +id: version-next-vendors +title: Vendors +original_id: vendors +--- + +Next to LIGO’s main pipeline, we use some other libraries, that are in the folder `vendors`. +## ligo-utils +This, quite expectedly, defines utilities that are used in LIGO. +There are three kinds of utilities, corresponding to their dependencies. + +`tezos-utils` contain utilities that depend on some Tezos libraries. + +`proto-alpha-utils` contain utilities that depend on the compilation of some Tezos protocol. It is very big and thus can’t be compiled in JS. This is because of a dependency to this that we don’t have LIGO in the browser yet. + +`simple-utils` contain most utilities. For instance, in `simple-utils` are `X_list` and `X_option`, that extend the `List` module and the `option` type found in `Pervasives`. + +Of particular interest in `simple-utils` is `trace.ml`, a module used pervasively in LIGO’s code-base. It deals with exceptions (and soon enough debugging annotations) in a functional manner. It offers a lot of utilities to build, combine and propagate exceptions. Given it’s used everywhere, that it relies on some advanced features of OCaml (higher order functions, ppx preprocessing) and that it exposes **a lot** of functions, it’s a good idea to look at this file’s documentation. +## tezos-modded +`tezos-modded` is a modded version of Tezos. There are modifications in it that are quite useful (exposing more functions from the protocol, giving more options to functions already defined), but not integrated yet. +It should in the end be integrated into the Tezos protocol, but until then, we use this. + diff --git a/gitlab-pages/website/versioned_docs/version-next/contributors/contributing/getting-started.md b/gitlab-pages/website/versioned_docs/version-next/contributors/contributing/getting-started.md new file mode 100644 index 000000000..25575476c --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-next/contributors/contributing/getting-started.md @@ -0,0 +1,41 @@ +--- +id: version-next-getting-started +title: Getting started +original_id: getting-started +--- + +## Where +As we’ve seen, LIGO is big, as such, it is easier to start focus on a specific part of LIGO. As very vague suggestions: +If you want to immediately see the result of your contributions, you might want to start with the Front-End. This is what most people will directly see of LIGO. +If you want to get into Programming Language Theory, you might want to start with the Middle-End. This is where the Type System and the Language Definition are (the closest thing so far that you’ll find in a research paper). +If you want to get into the nitty gritty details of compiling to special targets, you’ll want to focus on the Back-End. +If you want to develop tooling on top of LIGO (editor integration, for instance), you’ll want to look at `Ast_typed/types.ml`. This is where most information that is relevant to devs will be (for now). +If you really want to get a grasp of the whole pipeline, search for issues tagged with “Everything”, they’ll have you look at multiple parts of the code base. +## What +Likely, the first issues will be about: +Adding tests +Extending the languages by adding new operators +Adding tests +Refactoring +Writing documentation and tutorials for users +Adding tests +Writing internal documentation when you understand a part of the code base +>Tests are **really** important, we don’t have lots of them, and mostly regression ones. This can’t be stressed enough. Some features are missing not because we can’t add them, but because we don’t know so as no tests tell us they are missing. +## How +Issues will be added to the Gitlab, tagged with On-boarding and Front-End / Middle-End / Back-End / Everything. If you try to tackle one issue, and you have **any** problem, please tell us, by creating a new Gitlab issue, contacting us on Riot, Discord or even by mail! Problems might include: +Installing the repository or the tools needed to work on it +OCaml weirdness +Understanding undocumented parts of the code base +Documented parts of the code base too +**Anything really** + +--- + +## FAQ +### I don’t know much about OCaml, where should I start? What should I have in mind? +I’d suggesting going through Real World OCaml to get a feel for the language, to know what are its features, and to know what to Google when you’re lost. +Beyond that, I’d say, start hacking! Either on LIGO’s code base, or on any personal project. +There is a Discord server if you want real-time help (which makes things go way faster than waiting for an answer on stackoverflow or looking mindlessly at the monitor). +### I want to add [X] to LIGO! Where should I begin? +Trying to add a new feature from scratch instead of building upon one can be quite complicated. However, if you’re motivated, contact us! We’ll tell you what we see as the most likely plan to get the result you want to achieve. + diff --git a/gitlab-pages/website/versioned_docs/version-next/contributors/origin.md b/gitlab-pages/website/versioned_docs/version-next/contributors/origin.md new file mode 100644 index 000000000..3b3820ef0 --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-next/contributors/origin.md @@ -0,0 +1,11 @@ +--- +id: version-next-origin +title: Origin +original_id: origin +--- + +LIGO is a programming language that aims to provide developers with an uncomplicated and safer way to implement smart-contracts. LIGO is currently being implemented for the Tezos blockchain and as a result, it compiles down to Michelson - the native smart-contract language of Tezos. + +> Smart-contracts are programs that run within a blockchain network. + +LIGO was initially meant to be a language for developing Marigold, on top of a hacky framework called Meta-Michelson. However, due to the attention received by the Tezos community, a decision has been put into action to develop LIGO as a standalone language that will support Tezos directly as well. \ No newline at end of file diff --git a/gitlab-pages/website/versioned_docs/version-next/contributors/philosophy.md b/gitlab-pages/website/versioned_docs/version-next/contributors/philosophy.md new file mode 100644 index 000000000..349c6d131 --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-next/contributors/philosophy.md @@ -0,0 +1,46 @@ +--- +id: version-next-philosophy +title: Philosophy +original_id: philosophy +--- + +To understand LIGO’s design choices, it’s important to get its philosophy. There are two main concerns that we have in mind when building LIGO. + + + +## Safety +Once a smart-contract is deployed, it will likely be impossible to change it. You must get it right on the first try, and LIGO should help as much as possible. There are multiple ways to make LIGO a safer language for smart-contracts. + +### Automated Testing +Automated Testing is the process through which a program will run some other program, and check that this other program behaves correctly. +There already is a testing library for LIGO programs written in OCaml that is used to test LIGO itself. Making it accessible to users will greatly improve safety. A way to do so would be to make it accessible from within LIGO. + +### Static Analysis +Static analysis is the process of having a program analyze another one. +For instance, type systems are a kind of static analysis through which it is possible to find lots of bugs. There is already a fairly simple type system in LIGO, and we plan to make it much stronger. + +### Conciseness +Writing less code gives you less room to introduce errors and that's why LIGO encourages writing lean rather than chunky smart-contracts. + +--- + +## Ergonomics +Having an ergonomic product is crucial on multiple levels: +Making features easily accessible ensures they’ll actually get used. +Not wasting users time on idiosyncrasies frees more time for making contracts safer or building apps. +Keeping users in a Flow state makes it possible to introduce more complex features in the language. +There are multiple ways to improve ergonomics. + +### The Language +LIGO should contain as few surprises as possible. This is usually known as the principle of least surprise. + +Most programmers who will use LIGO have already spent a lot of time learning to develop in an existing language, with its own set of conventions and expectations. These expectations are often the most important to accommodate. This is why C-style syntaxes are especially popular (e.g. JavaScript), C-style is well known and new languages want to take advantage of that familiarity. Therefore as an extension of the principle of least surprise, LIGO supports more than one syntax. The least surprising language for a new developer is the one that they have already learned how to use. It’s probably not practical to replicate the syntax of every programming language, so LIGO takes the approach of replicating the structure used by languages from a particular paradigm. + +It is packaged in a Docker container, so that no particular installation instructions are required. + +### Editor Support +Without editor support, a lot of manipulations are very cumbersome. Checking for errors, testing, examining code, refactoring code, etc. This is why there is ongoing work on editor support, starting with highlighting and code-folding. + +### Docs +Docs include documentation of the languages, tutorials, as well as examples and design patterns. +We’re a long way from there. But having extensive docs is part of our goals. \ No newline at end of file diff --git a/gitlab-pages/website/versioned_docs/version-next/contributors/road-map/long-term.md b/gitlab-pages/website/versioned_docs/version-next/contributors/road-map/long-term.md new file mode 100644 index 000000000..1dd099373 --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-next/contributors/road-map/long-term.md @@ -0,0 +1,21 @@ +--- +id: version-next-long-term +title: Longer term +original_id: long-term +--- + +Soon enough, the Schema for the front-end will look like this: + +![LIGO Overview](/img/generic-front-end.png) + +Basically, as we support more syntaxes (up to half a dozen), we’ll have a bigger need for a unified representation and generation of the helpers around it. +For instance: +Parsers. So far, parsers are generated by LR grammars. LR grammars have a steep learning curve, regularly making not worth it for someone to learn the whole formalism to extend a given grammar with a few cases. Generating those LR Grammars would thus save a lot of time. +Displayers. The idea is that if you can parse and display code in a given syntax, it becomes much easier to have a translator between each syntax. So that not only it becomes possible for users to write code in their favorite syntax, but also to only read code in their favorite syntax. +BNFs. BNF grammars are a common formalism to represent grammars. They are understood by many tools, and are an easy way to document a given syntax. +## Super Type System +Soon enough, the Schema for the middle-end will look like this: +![LIGO Overview](/img/super-type-system.png) +Basically, this schema shows that the Back-End will stop being the main consumer of the Typed AST, and the External World will in its stead. +As such, annotating the AST with quality information, documenting it and exposing the libraries that produced the information in the first place will be paramount. +The imagined type-system so far is a mixture of MLF, extensible data-types and Algebraic Effects. \ No newline at end of file diff --git a/gitlab-pages/website/versioned_docs/version-next/contributors/road-map/short-term.md b/gitlab-pages/website/versioned_docs/version-next/contributors/road-map/short-term.md new file mode 100644 index 000000000..7deca1c7a --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-next/contributors/road-map/short-term.md @@ -0,0 +1,21 @@ +--- +id: version-next-short-term +title: Short term +original_id: short-term +--- + +## Documentation and Testing +We lack documentation and tests. Top priority. +Tests are needed at multiple levels: +Unit tests. Most utility functions should be tested individually. +Interface tests. Parts of the pipeline (Typer, Transpiler-Compiler, etc.) should be tested as black boxes. +Integration tests. Typical user scenarios, as interacted with the CLI, should be tested. +## Exposing Features +Many features have already been developed or nearly developed, and mostly need to be shown some attention, and then be exposed to the outside world, for instance: +Testing LIGO code +Step-by-step interpreter +LIGO in the browser +Propagating source locations for error messages +Dry-running a contract +## Refactoring +For the longer-term, it’s crucial to refactor big parts of the code base. This is needed to lower the complexity of the code base, so that it’s easier both for everyone (including API consumers) to interact with it. diff --git a/gitlab-pages/website/versioned_docs/version-next/language-basics-entrypoints.md b/gitlab-pages/website/versioned_docs/version-next/language-basics-entrypoints.md new file mode 100644 index 000000000..aa439932b --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-next/language-basics-entrypoints.md @@ -0,0 +1,45 @@ +--- +id: version-next-language-basics-entrypoints +title: Entrypoints +original_id: language-basics-entrypoints +--- + +## Defining an entry point + + + +```Pascal +function main (const p : int ; const s : int) : (list(operation) * unit) is + block {skip} with ((nil : list(operation)), s + 1) +``` + + +## Multiple entry points + +Multiple entrypoints are currently not supported in Michelson, however with Ligo, you can work that around by using variants. + + + +```Pascal +// variant defining pseudo multi-entrypoint actions +type action is +| Increment of int +| Decrement of int + +function add (const a : int ; const b : int) : int is + block { skip } with a + b + +function subtract (const a : int ; const b : int) : int is + block { skip } with a - b + +// real entrypoint that re-routes the flow based on the action provided +function main (const p : action ; const s : int) : (list(operation) * int) is + block {skip} with ((nil : list(operation)), + case p of + | Increment n -> add(s, n) + | Decrement n -> subtract(s, n) + end) +``` + + + \ No newline at end of file diff --git a/gitlab-pages/website/versioned_docs/version-next/language-basics-functions.md b/gitlab-pages/website/versioned_docs/version-next/language-basics-functions.md new file mode 100644 index 000000000..eace19496 --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-next/language-basics-functions.md @@ -0,0 +1,23 @@ +--- +id: version-next-language-basics-functions +title: Functions +original_id: language-basics-functions +--- + +## Defining a function + + + +```Pascal +// multiply(1, 2) = 2 +function multiply (const a : int ; const b : int) : int is + begin + const result : int = a * b ; + end with result + +// add(1, 2) = 3 +function add (const a : int ; const b : int) : int is + block { skip } with a + b +``` + + \ No newline at end of file diff --git a/gitlab-pages/website/versioned_docs/version-next/language-basics-operators.md b/gitlab-pages/website/versioned_docs/version-next/language-basics-operators.md new file mode 100644 index 000000000..1a044a7ed --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-next/language-basics-operators.md @@ -0,0 +1,13 @@ +--- +id: version-next-language-basics-operators +title: Operators +original_id: language-basics-operators +--- + +## Available operators + +|Michelson |Pascaligo |Description | +|--- |--- |--- | +| `SENDER` | `sender` | Address that initiated the current transaction +| `SOURCE` | `source` | Address that initiated the transaction, which triggered the current transaction. (useful e.g. when there's a transaction sent by another contract) +| `AMOUNT` | `amount` | Amount of tez sent by the transaction that invoked the contract \ No newline at end of file diff --git a/gitlab-pages/website/versioned_docs/version-next/language-basics-variables.md b/gitlab-pages/website/versioned_docs/version-next/language-basics-variables.md new file mode 100644 index 000000000..eafcff363 --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-next/language-basics-variables.md @@ -0,0 +1,19 @@ +--- +id: version-next-language-basics-variables +title: Variables +original_id: language-basics-variables +--- + +## Defining a variable + + + +```Pascal +// int +const four : int = 4; + +// string +const name : string = "John Doe"; +``` + + \ No newline at end of file diff --git a/gitlab-pages/website/versioned_docs/version-next/setup-installation.md b/gitlab-pages/website/versioned_docs/version-next/setup-installation.md new file mode 100644 index 000000000..424611dde --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-next/setup-installation.md @@ -0,0 +1,37 @@ +--- +id: version-next-setup-installation +title: Installation +original_id: setup-installation +--- + +There are currently two ways to get started with Ligo, both of those will allow you to use the Ligo CLI with your contracts. You can choose to use either the Docker image, or to compile & build the Ligo CLI yourself. + +## Docker + +> 🐳 You can find instructions on how to install Docker [here](https://docs.docker.com/install/). + +Easiest way to use LIGO is through the Docker image available at [Docker Hub](https://hub.docker.com/r/stovelabs/granary-ligo). Sources for the image can be found on [Github](https://github.com/stove-labs/granary/blob/develop/docker/ligo/Dockerfile). +You can either run the docker image yourself, or you can setup a global ligo executable as shown below. + +### Setting up a globally available `ligo` executable +```zsh +wget https://gitlab.com/maht0rz/ligo-documentation/blob/master/ligo-docker.sh && \ +sudo cp ligo-docker.sh /usr/local/bin/ligo && \ +sudo chmod +x /usr/local/bin/ligo && \ +rm ligo-docker.sh +``` + +> ⚠️ Please note that the **current docker image is quite chunky**, it may take a while to download depending on your internet connection. + +**Verify your ligo installation by running:** +```zsh +ligo --help +``` + + +## Manual installation + +For now, please refer to the steps described in the [Dockerfile](https://github.com/stove-labs/granary/blob/develop/docker/ligo/Dockerfile). + + + diff --git a/gitlab-pages/website/versioned_sidebars/version-next-sidebars.json b/gitlab-pages/website/versioned_sidebars/version-next-sidebars.json new file mode 100644 index 000000000..c3a53ecbc --- /dev/null +++ b/gitlab-pages/website/versioned_sidebars/version-next-sidebars.json @@ -0,0 +1,36 @@ +{ + "version-next-docs": { + "Setup": [ + "version-next-setup-installation" + ], + "Language Basics": [ + "version-next-language-basics-variables", + "version-next-language-basics-functions", + "version-next-language-basics-entrypoints", + "version-next-language-basics-operators" + ], + "API": [ + "version-next-api-cli-commands" + ] + }, + "version-next-contributors-docs": { + "Introduction": [ + "version-next-contributors/origin", + "version-next-contributors/philosophy" + ], + "Big Picture": [ + "version-next-contributors/big-picture/overview", + "version-next-contributors/big-picture/front-end", + "version-next-contributors/big-picture/middle-end", + "version-next-contributors/big-picture/back-end", + "version-next-contributors/big-picture/vendors" + ], + "Road Map": [ + "version-next-contributors/road-map/short-term", + "version-next-contributors/road-map/long-term" + ], + "Contributing": [ + "version-next-contributors/contributing/getting-started" + ] + } +} diff --git a/gitlab-pages/website/versions.json b/gitlab-pages/website/versions.json new file mode 100644 index 000000000..630ba2cc6 --- /dev/null +++ b/gitlab-pages/website/versions.json @@ -0,0 +1,3 @@ +[ + "next" +] From 0e6a3f6721df7aab2bcb45fc707f7189ac80890a Mon Sep 17 00:00:00 2001 From: Matej Sima Date: Thu, 6 Jun 2019 15:45:45 +0200 Subject: [PATCH 02/10] Update website versioning workflow --- .gitlab-ci.yml | 8 ++++---- gitlab-pages/.gitignore | 2 ++ gitlab-pages/website/package.json | 2 ++ gitlab-pages/website/pages/en/versions.js | 8 +------- gitlab-pages/website/postversion.js | 1 + gitlab-pages/website/{removeNext.js => preversion.js} | 0 .../versioned_docs/version-next/setup-installation.md | 2 ++ gitlab-pages/website/versions.json | 4 +--- 8 files changed, 13 insertions(+), 14 deletions(-) create mode 100644 gitlab-pages/website/postversion.js rename gitlab-pages/website/{removeNext.js => preversion.js} (100%) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 6fc7854ac..4dbf2bf3f 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -15,13 +15,11 @@ stages: - cd gitlab-pages/website - npm install script: - - rm -rf versioned_docs/version-next - - rm versioned_sidebars/version-next-sidebars.json - - node removeNext.js - npm run version next - npm run build + after_script: - cd ../.. - - cp -r gitlab-pages/website/build/ligo public + - cp -r gitlab-pages/website/build/ligo public artifacts: paths: - public @@ -121,6 +119,8 @@ stages: - master +# Pages are deployed from both master & dev, be careful not to override 'next' +# in case something gets merged into 'dev' while releasing. pages: <<: *website_build # only: diff --git a/gitlab-pages/.gitignore b/gitlab-pages/.gitignore index 5395ea795..3f87a979e 100644 --- a/gitlab-pages/.gitignore +++ b/gitlab-pages/.gitignore @@ -10,3 +10,5 @@ website/build/ website/yarn.lock website/node_modules website/i18n/* +website/versioned_docs/version-next +website/versioned_sidebars/version-next-sidebars.json \ No newline at end of file diff --git a/gitlab-pages/website/package.json b/gitlab-pages/website/package.json index e2dbb5afb..082937488 100644 --- a/gitlab-pages/website/package.json +++ b/gitlab-pages/website/package.json @@ -6,6 +6,8 @@ "publish-gh-pages": "docusaurus-publish", "write-translations": "docusaurus-write-translations", "version": "docusaurus-version", + "preversion": "node preversion.js", + "postversion": "node postversion.js", "rename-version": "docusaurus-rename-version" }, "devDependencies": { diff --git a/gitlab-pages/website/pages/en/versions.js b/gitlab-pages/website/pages/en/versions.js index 663a91167..a123ea192 100644 --- a/gitlab-pages/website/pages/en/versions.js +++ b/gitlab-pages/website/pages/en/versions.js @@ -28,7 +28,6 @@ function Versions(props) {

{siteConfig.title} Versions

-

New versions of this project are released every so often.

Current version (Stable)

@@ -53,10 +52,6 @@ function Versions(props) {
-

- This is the version that is configured automatically when you first - install this project. -

Pre-release versions

@@ -78,14 +73,13 @@ function Versions(props) {
-

Other text describing this section.

Past Versions

Here you can find previous versions of the documentation.

{versions.map( version => - version !== latestVersion && ( + version !== latestVersion && version !== "next" && (
{version} diff --git a/gitlab-pages/website/postversion.js b/gitlab-pages/website/postversion.js new file mode 100644 index 000000000..b53c4a1d0 --- /dev/null +++ b/gitlab-pages/website/postversion.js @@ -0,0 +1 @@ +require('./preversion'); \ No newline at end of file diff --git a/gitlab-pages/website/removeNext.js b/gitlab-pages/website/preversion.js similarity index 100% rename from gitlab-pages/website/removeNext.js rename to gitlab-pages/website/preversion.js diff --git a/gitlab-pages/website/versioned_docs/version-next/setup-installation.md b/gitlab-pages/website/versioned_docs/version-next/setup-installation.md index 424611dde..94e809cbb 100644 --- a/gitlab-pages/website/versioned_docs/version-next/setup-installation.md +++ b/gitlab-pages/website/versioned_docs/version-next/setup-installation.md @@ -34,4 +34,6 @@ ligo --help For now, please refer to the steps described in the [Dockerfile](https://github.com/stove-labs/granary/blob/develop/docker/ligo/Dockerfile). +## next-2 + diff --git a/gitlab-pages/website/versions.json b/gitlab-pages/website/versions.json index 630ba2cc6..27dbe6f91 100644 --- a/gitlab-pages/website/versions.json +++ b/gitlab-pages/website/versions.json @@ -1,3 +1 @@ -[ - "next" -] +["0.0.1"] \ No newline at end of file From c0cc9c76dcb759a60b93ba81035a505c102c7263 Mon Sep 17 00:00:00 2001 From: Matej Sima Date: Thu, 6 Jun 2019 16:49:47 +0200 Subject: [PATCH 03/10] Add updated installation guide, restructure docs --- .gitlab-ci.yml | 9 ++-- gitlab-pages/.gitignore | 2 + gitlab-pages/Makefile | 2 - .../documentation-and-releases.md | 20 +++++++++ .../{contributing => }/getting-started.md | 0 gitlab-pages/docs/setup-installation.md | 24 ++++++----- gitlab-pages/website/sidebars.json | 5 +-- .../contributing/getting-started.md | 41 ------------------- .../version-next/setup-installation.md | 26 ++++++------ .../version-next-sidebars.json | 7 ++-- gitlab-pages/website/versions.json | 2 +- scripts/installer.sh | 13 ++++-- 12 files changed, 68 insertions(+), 83 deletions(-) delete mode 100644 gitlab-pages/Makefile create mode 100644 gitlab-pages/docs/contributors/documentation-and-releases.md rename gitlab-pages/docs/contributors/{contributing => }/getting-started.md (100%) delete mode 100644 gitlab-pages/website/versioned_docs/version-next/contributors/contributing/getting-started.md diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 4dbf2bf3f..54f0f7024 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -31,7 +31,7 @@ stages: .docker_build: &docker_build script: - - docker build -t $LIGO_REGISTRY_IMAGE:latest -f ./docker/Dockerfile . + - docker build -t $LIGO_REGISTRY_IMAGE:next -f ./docker/Dockerfile . .before_script: &before_script before_script: @@ -105,8 +105,9 @@ stages: <<: *docker_build except: - master + - dev -# When a MR/PR is merged to master +# When a MR/PR is merged to dev # take the previous build and publish it to Docker Hub .build-and-publish-latest-docker-image: stage: build_and_deploy_docker @@ -114,9 +115,9 @@ stages: <<: *docker_build after_script: - docker login -u $LIGO_REGISTRY_USER -p $LIGO_REGISTRY_PASSWORD - - docker push $LIGO_REGISTRY_IMAGE:latest + - docker push $LIGO_REGISTRY_IMAGE:next only: - - master + - dev # Pages are deployed from both master & dev, be careful not to override 'next' diff --git a/gitlab-pages/.gitignore b/gitlab-pages/.gitignore index 3f87a979e..7f1f9860d 100644 --- a/gitlab-pages/.gitignore +++ b/gitlab-pages/.gitignore @@ -10,5 +10,7 @@ website/build/ website/yarn.lock website/node_modules website/i18n/* +website/versioned_docs/version-mock website/versioned_docs/version-next +website/versioned_sidebars/version-mock-sidebars.json website/versioned_sidebars/version-next-sidebars.json \ No newline at end of file diff --git a/gitlab-pages/Makefile b/gitlab-pages/Makefile deleted file mode 100644 index fab8d821f..000000000 --- a/gitlab-pages/Makefile +++ /dev/null @@ -1,2 +0,0 @@ -up: - docker-compose up diff --git a/gitlab-pages/docs/contributors/documentation-and-releases.md b/gitlab-pages/docs/contributors/documentation-and-releases.md new file mode 100644 index 000000000..977c9a9c7 --- /dev/null +++ b/gitlab-pages/docs/contributors/documentation-and-releases.md @@ -0,0 +1,20 @@ +--- +id: documentation-and-releases +title: Documentation and releases +--- + + +## Documentation + +In case you'd like to contribute to the docs, you can find them at [`gitlab-pages/docs`]() in their raw markdown form. +Deployment of the docs/website for LIGO is taken care of within the CI, from `dev` and `master` branches. + +## Releases & versioning + +### Development releases (next) + +Development releases of Ligo are tagged as `next` and are built with each commit to the `dev` branch. Both the docker image & the website are published automatically. + +### Stable releases + +Releases tagged with version numbers `x.x.x` are built manually, both docs & the docker image. While deployment of the website is handled by the CI. diff --git a/gitlab-pages/docs/contributors/contributing/getting-started.md b/gitlab-pages/docs/contributors/getting-started.md similarity index 100% rename from gitlab-pages/docs/contributors/contributing/getting-started.md rename to gitlab-pages/docs/contributors/getting-started.md diff --git a/gitlab-pages/docs/setup-installation.md b/gitlab-pages/docs/setup-installation.md index a08db5e30..23b8caf19 100644 --- a/gitlab-pages/docs/setup-installation.md +++ b/gitlab-pages/docs/setup-installation.md @@ -5,22 +5,24 @@ title: Installation There are currently two ways to get started with Ligo, both of those will allow you to use the Ligo CLI with your contracts. You can choose to use either the Docker image, or to compile & build the Ligo CLI yourself. -## Docker +## Dockerized installation (recommended) > 🐳 You can find instructions on how to install Docker [here](https://docs.docker.com/install/). -Easiest way to use LIGO is through the Docker image available at [Docker Hub](https://hub.docker.com/r/stovelabs/granary-ligo). Sources for the image can be found on [Github](https://github.com/stove-labs/granary/blob/develop/docker/ligo/Dockerfile). +Easiest way to use LIGO is through the Docker image available at [Docker Hub](https://hub.docker.com/r/ligolang/ligo). Sources for the image can be found on [Gitlab](https://gitlab.com/ligolang/ligo/blob/master/docker/Dockerfile). You can either run the docker image yourself, or you can setup a global ligo executable as shown below. ### Setting up a globally available `ligo` executable -```zsh -wget https://gitlab.com/maht0rz/ligo-documentation/blob/master/ligo-docker.sh && \ -sudo cp ligo-docker.sh /usr/local/bin/ligo && \ -sudo chmod +x /usr/local/bin/ligo && \ -rm ligo-docker.sh -``` -> ⚠️ Please note that the **current docker image is quite chunky**, it may take a while to download depending on your internet connection. +> You can install additional ligo versions by replacing `next` with the required version number + +```zsh +# next (pre-release) +curl https://gitlab.com/ligolang/ligo/blob/master/scripts/installer.sh | bash "next" + +# e.g. 1.0.0 (stable) +curl https://gitlab.com/ligolang/ligo/blob/master/scripts/installer.sh | bash "1.0.0" +``` **Verify your ligo installation by running:** ```zsh @@ -28,9 +30,9 @@ ligo --help ``` -## Manual installation +## Manual installation (advanced) -For now, please refer to the steps described in the [Dockerfile](https://github.com/stove-labs/granary/blob/develop/docker/ligo/Dockerfile). +For now, please refer to the steps described in the [Dockerfile](https://gitlab.com/ligolang/ligo/blob/master/docker/Dockerfile). diff --git a/gitlab-pages/website/sidebars.json b/gitlab-pages/website/sidebars.json index 2f0f8b73f..281a5d720 100644 --- a/gitlab-pages/website/sidebars.json +++ b/gitlab-pages/website/sidebars.json @@ -5,7 +5,7 @@ "API": ["api-cli-commands"] }, "contributors-docs": { - "Introduction": ["contributors/origin", "contributors/philosophy"], + "Introduction": ["contributors/origin", "contributors/philosophy", "contributors/getting-started", "contributors/documentation-and-releases"], "Big Picture": [ "contributors/big-picture/overview", "contributors/big-picture/front-end", @@ -13,7 +13,6 @@ "contributors/big-picture/back-end", "contributors/big-picture/vendors" ], - "Road Map": ["contributors/road-map/short-term", "contributors/road-map/long-term"], - "Contributing": ["contributors/contributing/getting-started"] + "Road Map": ["contributors/road-map/short-term", "contributors/road-map/long-term"] } } diff --git a/gitlab-pages/website/versioned_docs/version-next/contributors/contributing/getting-started.md b/gitlab-pages/website/versioned_docs/version-next/contributors/contributing/getting-started.md deleted file mode 100644 index 25575476c..000000000 --- a/gitlab-pages/website/versioned_docs/version-next/contributors/contributing/getting-started.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -id: version-next-getting-started -title: Getting started -original_id: getting-started ---- - -## Where -As we’ve seen, LIGO is big, as such, it is easier to start focus on a specific part of LIGO. As very vague suggestions: -If you want to immediately see the result of your contributions, you might want to start with the Front-End. This is what most people will directly see of LIGO. -If you want to get into Programming Language Theory, you might want to start with the Middle-End. This is where the Type System and the Language Definition are (the closest thing so far that you’ll find in a research paper). -If you want to get into the nitty gritty details of compiling to special targets, you’ll want to focus on the Back-End. -If you want to develop tooling on top of LIGO (editor integration, for instance), you’ll want to look at `Ast_typed/types.ml`. This is where most information that is relevant to devs will be (for now). -If you really want to get a grasp of the whole pipeline, search for issues tagged with “Everything”, they’ll have you look at multiple parts of the code base. -## What -Likely, the first issues will be about: -Adding tests -Extending the languages by adding new operators -Adding tests -Refactoring -Writing documentation and tutorials for users -Adding tests -Writing internal documentation when you understand a part of the code base ->Tests are **really** important, we don’t have lots of them, and mostly regression ones. This can’t be stressed enough. Some features are missing not because we can’t add them, but because we don’t know so as no tests tell us they are missing. -## How -Issues will be added to the Gitlab, tagged with On-boarding and Front-End / Middle-End / Back-End / Everything. If you try to tackle one issue, and you have **any** problem, please tell us, by creating a new Gitlab issue, contacting us on Riot, Discord or even by mail! Problems might include: -Installing the repository or the tools needed to work on it -OCaml weirdness -Understanding undocumented parts of the code base -Documented parts of the code base too -**Anything really** - ---- - -## FAQ -### I don’t know much about OCaml, where should I start? What should I have in mind? -I’d suggesting going through Real World OCaml to get a feel for the language, to know what are its features, and to know what to Google when you’re lost. -Beyond that, I’d say, start hacking! Either on LIGO’s code base, or on any personal project. -There is a Discord server if you want real-time help (which makes things go way faster than waiting for an answer on stackoverflow or looking mindlessly at the monitor). -### I want to add [X] to LIGO! Where should I begin? -Trying to add a new feature from scratch instead of building upon one can be quite complicated. However, if you’re motivated, contact us! We’ll tell you what we see as the most likely plan to get the result you want to achieve. - diff --git a/gitlab-pages/website/versioned_docs/version-next/setup-installation.md b/gitlab-pages/website/versioned_docs/version-next/setup-installation.md index 94e809cbb..748f7b40e 100644 --- a/gitlab-pages/website/versioned_docs/version-next/setup-installation.md +++ b/gitlab-pages/website/versioned_docs/version-next/setup-installation.md @@ -6,22 +6,24 @@ original_id: setup-installation There are currently two ways to get started with Ligo, both of those will allow you to use the Ligo CLI with your contracts. You can choose to use either the Docker image, or to compile & build the Ligo CLI yourself. -## Docker +## Dockerized installation (recommended) > 🐳 You can find instructions on how to install Docker [here](https://docs.docker.com/install/). -Easiest way to use LIGO is through the Docker image available at [Docker Hub](https://hub.docker.com/r/stovelabs/granary-ligo). Sources for the image can be found on [Github](https://github.com/stove-labs/granary/blob/develop/docker/ligo/Dockerfile). +Easiest way to use LIGO is through the Docker image available at [Docker Hub](https://hub.docker.com/r/ligolang/ligo). Sources for the image can be found on [Gitlab](https://gitlab.com/ligolang/ligo/blob/master/docker/Dockerfile). You can either run the docker image yourself, or you can setup a global ligo executable as shown below. ### Setting up a globally available `ligo` executable -```zsh -wget https://gitlab.com/maht0rz/ligo-documentation/blob/master/ligo-docker.sh && \ -sudo cp ligo-docker.sh /usr/local/bin/ligo && \ -sudo chmod +x /usr/local/bin/ligo && \ -rm ligo-docker.sh -``` -> ⚠️ Please note that the **current docker image is quite chunky**, it may take a while to download depending on your internet connection. +> You can install additional ligo versions by replacing `next` with the required version number + +```zsh +# next (pre-release) +curl https://gitlab.com/ligolang/ligo/blob/master/scripts/installer.sh | bash "next" + +# e.g. 1.0.0 (stable) +curl https://gitlab.com/ligolang/ligo/blob/master/scripts/installer.sh | bash "1.0.0" +``` **Verify your ligo installation by running:** ```zsh @@ -29,11 +31,9 @@ ligo --help ``` -## Manual installation +## Manual installation (advanced) -For now, please refer to the steps described in the [Dockerfile](https://github.com/stove-labs/granary/blob/develop/docker/ligo/Dockerfile). +For now, please refer to the steps described in the [Dockerfile](https://gitlab.com/ligolang/ligo/blob/master/docker/Dockerfile). -## next-2 - diff --git a/gitlab-pages/website/versioned_sidebars/version-next-sidebars.json b/gitlab-pages/website/versioned_sidebars/version-next-sidebars.json index c3a53ecbc..cf527cf2b 100644 --- a/gitlab-pages/website/versioned_sidebars/version-next-sidebars.json +++ b/gitlab-pages/website/versioned_sidebars/version-next-sidebars.json @@ -16,7 +16,9 @@ "version-next-contributors-docs": { "Introduction": [ "version-next-contributors/origin", - "version-next-contributors/philosophy" + "version-next-contributors/philosophy", + "version-next-contributors/getting-started", + "version-next-contributors/documentation-and-releases" ], "Big Picture": [ "version-next-contributors/big-picture/overview", @@ -28,9 +30,6 @@ "Road Map": [ "version-next-contributors/road-map/short-term", "version-next-contributors/road-map/long-term" - ], - "Contributing": [ - "version-next-contributors/contributing/getting-started" ] } } diff --git a/gitlab-pages/website/versions.json b/gitlab-pages/website/versions.json index 27dbe6f91..0637a088a 100644 --- a/gitlab-pages/website/versions.json +++ b/gitlab-pages/website/versions.json @@ -1 +1 @@ -["0.0.1"] \ No newline at end of file +[] \ No newline at end of file diff --git a/scripts/installer.sh b/scripts/installer.sh index eb56165ca..948cabe92 100755 --- a/scripts/installer.sh +++ b/scripts/installer.sh @@ -3,10 +3,15 @@ # curl https://gitlab.com/ligolang/ligo/blob/master/scripts/installer.sh | bash # Make sure the marigold/ligo image is published at docker hub first set -euET -o pipefail -echo "Installing LIGO" +version=$1 +printf "\nInstalling LIGO ($version)\n\n" # Install the ligo.sh from master -wget https://gitlab.com/ligolang/ligo/blob/master/scripts/ligo.sh +wget https://gitlab.com/ligolang/ligo/raw/master/scripts/ligo.sh + + +# Overwrite LIGO version in the executable +sed -i '' "s/latest/$version/g" ligo.sh # Copy the exucutable to the appropriate directory sudo cp ligo.sh /usr/local/bin/ligo @@ -14,7 +19,7 @@ sudo chmod +x /usr/local/bin/ligo rm ligo.sh # Pull the docker image used by ligo.sh -docker pull ligolang/ligo:latest +docker pull "ligolang/ligo:$version" # Installation finished, try running 'ligo' from your CLI -echo "Installation successful, try to run 'ligo --help' now. \n" \ No newline at end of file +printf "\nInstallation successful, try to run 'ligo --help' now.\n" \ No newline at end of file From a75b16037f020bd9e6d4515dc6b98b8ca9751c18 Mon Sep 17 00:00:00 2001 From: Matej Sima Date: Thu, 6 Jun 2019 16:53:00 +0200 Subject: [PATCH 04/10] Added a 'mock' version for docs due to technical reasons --- gitlab-pages/.gitignore | 2 - .../version-mock/api-cli-commands.md | 48 +++++++++++++++++++ .../contributors/big-picture/back-end.md | 19 ++++++++ .../contributors/big-picture/front-end.md | 16 +++++++ .../contributors/big-picture/middle-end.md | 17 +++++++ .../contributors/big-picture/overview.md | 17 +++++++ .../contributors/big-picture/vendors.md | 22 +++++++++ .../documentation-and-releases.md | 21 ++++++++ .../contributors/getting-started.md | 41 ++++++++++++++++ .../version-mock/contributors/origin.md | 11 +++++ .../version-mock/contributors/philosophy.md | 46 ++++++++++++++++++ .../contributors/road-map/long-term.md | 21 ++++++++ .../contributors/road-map/short-term.md | 21 ++++++++ .../language-basics-entrypoints.md | 45 +++++++++++++++++ .../version-mock/language-basics-functions.md | 23 +++++++++ .../version-mock/language-basics-operators.md | 13 +++++ .../version-mock/language-basics-variables.md | 19 ++++++++ .../version-mock/setup-installation.md | 39 +++++++++++++++ .../version-mock-sidebars.json | 35 ++++++++++++++ gitlab-pages/website/versions.json | 2 +- 20 files changed, 475 insertions(+), 3 deletions(-) create mode 100644 gitlab-pages/website/versioned_docs/version-mock/api-cli-commands.md create mode 100644 gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/back-end.md create mode 100644 gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/front-end.md create mode 100644 gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/middle-end.md create mode 100644 gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/overview.md create mode 100644 gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/vendors.md create mode 100644 gitlab-pages/website/versioned_docs/version-mock/contributors/documentation-and-releases.md create mode 100644 gitlab-pages/website/versioned_docs/version-mock/contributors/getting-started.md create mode 100644 gitlab-pages/website/versioned_docs/version-mock/contributors/origin.md create mode 100644 gitlab-pages/website/versioned_docs/version-mock/contributors/philosophy.md create mode 100644 gitlab-pages/website/versioned_docs/version-mock/contributors/road-map/long-term.md create mode 100644 gitlab-pages/website/versioned_docs/version-mock/contributors/road-map/short-term.md create mode 100644 gitlab-pages/website/versioned_docs/version-mock/language-basics-entrypoints.md create mode 100644 gitlab-pages/website/versioned_docs/version-mock/language-basics-functions.md create mode 100644 gitlab-pages/website/versioned_docs/version-mock/language-basics-operators.md create mode 100644 gitlab-pages/website/versioned_docs/version-mock/language-basics-variables.md create mode 100644 gitlab-pages/website/versioned_docs/version-mock/setup-installation.md create mode 100644 gitlab-pages/website/versioned_sidebars/version-mock-sidebars.json diff --git a/gitlab-pages/.gitignore b/gitlab-pages/.gitignore index 7f1f9860d..3f87a979e 100644 --- a/gitlab-pages/.gitignore +++ b/gitlab-pages/.gitignore @@ -10,7 +10,5 @@ website/build/ website/yarn.lock website/node_modules website/i18n/* -website/versioned_docs/version-mock website/versioned_docs/version-next -website/versioned_sidebars/version-mock-sidebars.json website/versioned_sidebars/version-next-sidebars.json \ No newline at end of file diff --git a/gitlab-pages/website/versioned_docs/version-mock/api-cli-commands.md b/gitlab-pages/website/versioned_docs/version-mock/api-cli-commands.md new file mode 100644 index 000000000..7aa43f1c6 --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-mock/api-cli-commands.md @@ -0,0 +1,48 @@ +--- +id: version-mock-api-cli-commands +title: CLI Commands +original_id: api-cli-commands +--- + +Contracts written in Ligo can be compiled using the `ligo` executable. + + +## Compiling a contract + +Compile your contract with a specific entry point. + +```zsh +ligo compile-contract SOURCE_FILE [ENTRY_POINT] +``` + +#### Example + +```zsh +ligo compile-contract examples/counter.ligo main +``` + +## Defining the initial storage + +If your contract implements a sophisticated storage, you can compile a Ligo expression into a Michelson value quite easily. + +```zsh +ligo compile-storage SOURCE_FILE ENTRY_POINT EXPRESSION +``` + +#### Example +```zsh +ligo compile-storage examples/counter.ligo main 5 +# Outputs: 5 +``` + +## Invoking the contract with a parameter + +```zsh +ligo compile-parameter SOURCE_FILE ENTRY_POINT EXPRESSION +``` + +#### Example +```zsh +ligo compile-parameter examples/counter.ligo main "Increment(5)" +# Outputs: (Right 5) +``` \ No newline at end of file diff --git a/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/back-end.md b/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/back-end.md new file mode 100644 index 000000000..f2833fbec --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/back-end.md @@ -0,0 +1,19 @@ +--- +id: version-mock-back-end +title: Back End +original_id: back-end +--- + +The Back-End is the part that compiles down to Michelson. Instead of a single compilation step, it is separated in two parts. +## Transpiler and Mini_C +The Transpiler is a function that takes as input the Typed AST, and outputs expressions in a language that is basically a Michelson based on with named variables and first-class-environments. +On the one hand, there are cases in the AST like `E_if_bool` or `E_make_empty_list` that would be directly translated in Michelson like `IF {} {}` or `NIL`. +On the other hand, there are cases in the AST like `E_variable` or `E_environment_select` that specifically target the compiler. +The files of the Transpiler are in `transpiler/`, while those of Mini_c are in `mini_c/`. +## Compiler +The previous LIGO’s compilation to Michelson model was quite complicated. The current one is quite straightforward, where the environment of variables (x -> 12, y -> “foo”) is compiled as Michelson stack (12 :: foo). +It has been simplified for multiple reasons: +Having a simple model reduces its number of points of failure. +Having a simple model makes optimizing it easier. +We submitted a change to the Tezos’ protocol that actually make it more efficient. + diff --git a/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/front-end.md b/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/front-end.md new file mode 100644 index 000000000..03610e0d4 --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/front-end.md @@ -0,0 +1,16 @@ +--- +id: version-mock-front-end +title: Front End +original_id: front-end +--- + +The Front-End is the part that deals with all syntactical matters. LIGO supports multiple Front-Ends. Each Front-End is composed of three different parts. +## Parser +A Parser is a function that takes a string of source code and outputs a structured representation of the program. This part usually uses Menhir, a parser generator compatible with OCaml. +Its files are in `parser/parser_name`. +## Concrete Syntax Tree +The CST is the aforementioned structured representation of the program. Is is structurally very close to the source code, and is mostly an intermediary there because manipulating string is not practical. +Its files are in `parser/parser_name`. +## Simplifier +A Simplifier is a function that takes a CST and outputs the corresponding Common AST. This is the actual bridge between a given syntax and LIGO. +Its files are in `simplify/parser_name`. diff --git a/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/middle-end.md b/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/middle-end.md new file mode 100644 index 000000000..716df9b2b --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/middle-end.md @@ -0,0 +1,17 @@ +--- +id: version-mock-middle-end +title: Middle End +original_id: middle-end +--- + +The Middle-End is the core of LIGO. It is also composed of three parts. +## Common AST +The Common AST is the closest thing to what could be called “LIGO lang”. As such, it should be as simple as possible. Collapsing particular cases in more general constructs is encouraged. Documenting it is crucial for people who’ll write new parsers or editor support for Front-end related things. +Its files are in `ast_simplified/`, of interest is the definition of the AST itself in `ast_simplified/types.ml`. +## Type Checker +The Type Checker, among other things, checks that a given AST is valid with regard to type-safety. It also annotates expressions with their types, free-variables and local environments. +As time passes, we want to make the type-system stronger, to encode arbitrarily complex properties in an extensible manner. +Its files are in `typer/`. +## Typed AST +The Typed AST is the result of Type Checker. On top of it, we also want to define/export many features aiming at making building tools on top LIGO as easy as possible. +Its files are in `ast_typed/`, of interest is the definition of the Typed AST itself in `ast_typed/types.ml`. diff --git a/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/overview.md b/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/overview.md new file mode 100644 index 000000000..08125b669 --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/overview.md @@ -0,0 +1,17 @@ +--- +id: version-mock-overview +title: Overview +original_id: overview +--- + +After going through the design principles and a few considerations linked to them, getting the Big Picture needs diving in technical matters. + +![LIGO Overview](/img/big-picture-overview.png) + +As shown in the Schema, LIGO’s compiler is separated in roughly 3 separate parts: + +- The Middle End. This is the core of LIGO. It defines its core data-structure (the Common AST), and its type-checking algorithm. + +- The Front End. This is the bridge between a given syntax and the Common AST. + +- The Back End. This is the bridge between the Common AST and a given compilation target. Currently, our only target is Michelson, but we’ll also target Marigold, and if Tezos moves to Web Assembly, Web Assembly. diff --git a/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/vendors.md b/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/vendors.md new file mode 100644 index 000000000..0fc00eaf4 --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/vendors.md @@ -0,0 +1,22 @@ +--- +id: version-mock-vendors +title: Vendors +original_id: vendors +--- + +Next to LIGO’s main pipeline, we use some other libraries, that are in the folder `vendors`. +## ligo-utils +This, quite expectedly, defines utilities that are used in LIGO. +There are three kinds of utilities, corresponding to their dependencies. + +`tezos-utils` contain utilities that depend on some Tezos libraries. + +`proto-alpha-utils` contain utilities that depend on the compilation of some Tezos protocol. It is very big and thus can’t be compiled in JS. This is because of a dependency to this that we don’t have LIGO in the browser yet. + +`simple-utils` contain most utilities. For instance, in `simple-utils` are `X_list` and `X_option`, that extend the `List` module and the `option` type found in `Pervasives`. + +Of particular interest in `simple-utils` is `trace.ml`, a module used pervasively in LIGO’s code-base. It deals with exceptions (and soon enough debugging annotations) in a functional manner. It offers a lot of utilities to build, combine and propagate exceptions. Given it’s used everywhere, that it relies on some advanced features of OCaml (higher order functions, ppx preprocessing) and that it exposes **a lot** of functions, it’s a good idea to look at this file’s documentation. +## tezos-modded +`tezos-modded` is a modded version of Tezos. There are modifications in it that are quite useful (exposing more functions from the protocol, giving more options to functions already defined), but not integrated yet. +It should in the end be integrated into the Tezos protocol, but until then, we use this. + diff --git a/gitlab-pages/website/versioned_docs/version-mock/contributors/documentation-and-releases.md b/gitlab-pages/website/versioned_docs/version-mock/contributors/documentation-and-releases.md new file mode 100644 index 000000000..63c9b9f0d --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-mock/contributors/documentation-and-releases.md @@ -0,0 +1,21 @@ +--- +id: version-mock-documentation-and-releases +title: Documentation and releases +original_id: documentation-and-releases +--- + + +## Documentation + +In case you'd like to contribute to the docs, you can find them at [`gitlab-pages/docs`]() in their raw markdown form. +Deployment of the docs/website for LIGO is taken care of within the CI, from `dev` and `master` branches. + +## Releases & versioning + +### Development releases (next) + +Development releases of Ligo are tagged as `next` and are built with each commit to the `dev` branch. Both the docker image & the website are published automatically. + +### Stable releases + +Releases tagged with version numbers `x.x.x` are built manually, both docs & the docker image. While deployment of the website is handled by the CI. diff --git a/gitlab-pages/website/versioned_docs/version-mock/contributors/getting-started.md b/gitlab-pages/website/versioned_docs/version-mock/contributors/getting-started.md new file mode 100644 index 000000000..a8b9e08c6 --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-mock/contributors/getting-started.md @@ -0,0 +1,41 @@ +--- +id: version-mock-getting-started +title: Getting started +original_id: getting-started +--- + +## Where +As we’ve seen, LIGO is big, as such, it is easier to start focus on a specific part of LIGO. As very vague suggestions: +If you want to immediately see the result of your contributions, you might want to start with the Front-End. This is what most people will directly see of LIGO. +If you want to get into Programming Language Theory, you might want to start with the Middle-End. This is where the Type System and the Language Definition are (the closest thing so far that you’ll find in a research paper). +If you want to get into the nitty gritty details of compiling to special targets, you’ll want to focus on the Back-End. +If you want to develop tooling on top of LIGO (editor integration, for instance), you’ll want to look at `Ast_typed/types.ml`. This is where most information that is relevant to devs will be (for now). +If you really want to get a grasp of the whole pipeline, search for issues tagged with “Everything”, they’ll have you look at multiple parts of the code base. +## What +Likely, the first issues will be about: +Adding tests +Extending the languages by adding new operators +Adding tests +Refactoring +Writing documentation and tutorials for users +Adding tests +Writing internal documentation when you understand a part of the code base +>Tests are **really** important, we don’t have lots of them, and mostly regression ones. This can’t be stressed enough. Some features are missing not because we can’t add them, but because we don’t know so as no tests tell us they are missing. +## How +Issues will be added to the Gitlab, tagged with On-boarding and Front-End / Middle-End / Back-End / Everything. If you try to tackle one issue, and you have **any** problem, please tell us, by creating a new Gitlab issue, contacting us on Riot, Discord or even by mail! Problems might include: +Installing the repository or the tools needed to work on it +OCaml weirdness +Understanding undocumented parts of the code base +Documented parts of the code base too +**Anything really** + +--- + +## FAQ +### I don’t know much about OCaml, where should I start? What should I have in mind? +I’d suggesting going through Real World OCaml to get a feel for the language, to know what are its features, and to know what to Google when you’re lost. +Beyond that, I’d say, start hacking! Either on LIGO’s code base, or on any personal project. +There is a Discord server if you want real-time help (which makes things go way faster than waiting for an answer on stackoverflow or looking mindlessly at the monitor). +### I want to add [X] to LIGO! Where should I begin? +Trying to add a new feature from scratch instead of building upon one can be quite complicated. However, if you’re motivated, contact us! We’ll tell you what we see as the most likely plan to get the result you want to achieve. + diff --git a/gitlab-pages/website/versioned_docs/version-mock/contributors/origin.md b/gitlab-pages/website/versioned_docs/version-mock/contributors/origin.md new file mode 100644 index 000000000..ebf7c3402 --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-mock/contributors/origin.md @@ -0,0 +1,11 @@ +--- +id: version-mock-origin +title: Origin +original_id: origin +--- + +LIGO is a programming language that aims to provide developers with an uncomplicated and safer way to implement smart-contracts. LIGO is currently being implemented for the Tezos blockchain and as a result, it compiles down to Michelson - the native smart-contract language of Tezos. + +> Smart-contracts are programs that run within a blockchain network. + +LIGO was initially meant to be a language for developing Marigold, on top of a hacky framework called Meta-Michelson. However, due to the attention received by the Tezos community, a decision has been put into action to develop LIGO as a standalone language that will support Tezos directly as well. \ No newline at end of file diff --git a/gitlab-pages/website/versioned_docs/version-mock/contributors/philosophy.md b/gitlab-pages/website/versioned_docs/version-mock/contributors/philosophy.md new file mode 100644 index 000000000..5f859f0d8 --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-mock/contributors/philosophy.md @@ -0,0 +1,46 @@ +--- +id: version-mock-philosophy +title: Philosophy +original_id: philosophy +--- + +To understand LIGO’s design choices, it’s important to get its philosophy. There are two main concerns that we have in mind when building LIGO. + + + +## Safety +Once a smart-contract is deployed, it will likely be impossible to change it. You must get it right on the first try, and LIGO should help as much as possible. There are multiple ways to make LIGO a safer language for smart-contracts. + +### Automated Testing +Automated Testing is the process through which a program will run some other program, and check that this other program behaves correctly. +There already is a testing library for LIGO programs written in OCaml that is used to test LIGO itself. Making it accessible to users will greatly improve safety. A way to do so would be to make it accessible from within LIGO. + +### Static Analysis +Static analysis is the process of having a program analyze another one. +For instance, type systems are a kind of static analysis through which it is possible to find lots of bugs. There is already a fairly simple type system in LIGO, and we plan to make it much stronger. + +### Conciseness +Writing less code gives you less room to introduce errors and that's why LIGO encourages writing lean rather than chunky smart-contracts. + +--- + +## Ergonomics +Having an ergonomic product is crucial on multiple levels: +Making features easily accessible ensures they’ll actually get used. +Not wasting users time on idiosyncrasies frees more time for making contracts safer or building apps. +Keeping users in a Flow state makes it possible to introduce more complex features in the language. +There are multiple ways to improve ergonomics. + +### The Language +LIGO should contain as few surprises as possible. This is usually known as the principle of least surprise. + +Most programmers who will use LIGO have already spent a lot of time learning to develop in an existing language, with its own set of conventions and expectations. These expectations are often the most important to accommodate. This is why C-style syntaxes are especially popular (e.g. JavaScript), C-style is well known and new languages want to take advantage of that familiarity. Therefore as an extension of the principle of least surprise, LIGO supports more than one syntax. The least surprising language for a new developer is the one that they have already learned how to use. It’s probably not practical to replicate the syntax of every programming language, so LIGO takes the approach of replicating the structure used by languages from a particular paradigm. + +It is packaged in a Docker container, so that no particular installation instructions are required. + +### Editor Support +Without editor support, a lot of manipulations are very cumbersome. Checking for errors, testing, examining code, refactoring code, etc. This is why there is ongoing work on editor support, starting with highlighting and code-folding. + +### Docs +Docs include documentation of the languages, tutorials, as well as examples and design patterns. +We’re a long way from there. But having extensive docs is part of our goals. \ No newline at end of file diff --git a/gitlab-pages/website/versioned_docs/version-mock/contributors/road-map/long-term.md b/gitlab-pages/website/versioned_docs/version-mock/contributors/road-map/long-term.md new file mode 100644 index 000000000..00e85be19 --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-mock/contributors/road-map/long-term.md @@ -0,0 +1,21 @@ +--- +id: version-mock-long-term +title: Longer term +original_id: long-term +--- + +Soon enough, the Schema for the front-end will look like this: + +![LIGO Overview](/img/generic-front-end.png) + +Basically, as we support more syntaxes (up to half a dozen), we’ll have a bigger need for a unified representation and generation of the helpers around it. +For instance: +Parsers. So far, parsers are generated by LR grammars. LR grammars have a steep learning curve, regularly making not worth it for someone to learn the whole formalism to extend a given grammar with a few cases. Generating those LR Grammars would thus save a lot of time. +Displayers. The idea is that if you can parse and display code in a given syntax, it becomes much easier to have a translator between each syntax. So that not only it becomes possible for users to write code in their favorite syntax, but also to only read code in their favorite syntax. +BNFs. BNF grammars are a common formalism to represent grammars. They are understood by many tools, and are an easy way to document a given syntax. +## Super Type System +Soon enough, the Schema for the middle-end will look like this: +![LIGO Overview](/img/super-type-system.png) +Basically, this schema shows that the Back-End will stop being the main consumer of the Typed AST, and the External World will in its stead. +As such, annotating the AST with quality information, documenting it and exposing the libraries that produced the information in the first place will be paramount. +The imagined type-system so far is a mixture of MLF, extensible data-types and Algebraic Effects. \ No newline at end of file diff --git a/gitlab-pages/website/versioned_docs/version-mock/contributors/road-map/short-term.md b/gitlab-pages/website/versioned_docs/version-mock/contributors/road-map/short-term.md new file mode 100644 index 000000000..4de1579d7 --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-mock/contributors/road-map/short-term.md @@ -0,0 +1,21 @@ +--- +id: version-mock-short-term +title: Short term +original_id: short-term +--- + +## Documentation and Testing +We lack documentation and tests. Top priority. +Tests are needed at multiple levels: +Unit tests. Most utility functions should be tested individually. +Interface tests. Parts of the pipeline (Typer, Transpiler-Compiler, etc.) should be tested as black boxes. +Integration tests. Typical user scenarios, as interacted with the CLI, should be tested. +## Exposing Features +Many features have already been developed or nearly developed, and mostly need to be shown some attention, and then be exposed to the outside world, for instance: +Testing LIGO code +Step-by-step interpreter +LIGO in the browser +Propagating source locations for error messages +Dry-running a contract +## Refactoring +For the longer-term, it’s crucial to refactor big parts of the code base. This is needed to lower the complexity of the code base, so that it’s easier both for everyone (including API consumers) to interact with it. diff --git a/gitlab-pages/website/versioned_docs/version-mock/language-basics-entrypoints.md b/gitlab-pages/website/versioned_docs/version-mock/language-basics-entrypoints.md new file mode 100644 index 000000000..b645fbbbb --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-mock/language-basics-entrypoints.md @@ -0,0 +1,45 @@ +--- +id: version-mock-language-basics-entrypoints +title: Entrypoints +original_id: language-basics-entrypoints +--- + +## Defining an entry point + + + +```Pascal +function main (const p : int ; const s : int) : (list(operation) * unit) is + block {skip} with ((nil : list(operation)), s + 1) +``` + + +## Multiple entry points + +Multiple entrypoints are currently not supported in Michelson, however with Ligo, you can work that around by using variants. + + + +```Pascal +// variant defining pseudo multi-entrypoint actions +type action is +| Increment of int +| Decrement of int + +function add (const a : int ; const b : int) : int is + block { skip } with a + b + +function subtract (const a : int ; const b : int) : int is + block { skip } with a - b + +// real entrypoint that re-routes the flow based on the action provided +function main (const p : action ; const s : int) : (list(operation) * int) is + block {skip} with ((nil : list(operation)), + case p of + | Increment n -> add(s, n) + | Decrement n -> subtract(s, n) + end) +``` + + + \ No newline at end of file diff --git a/gitlab-pages/website/versioned_docs/version-mock/language-basics-functions.md b/gitlab-pages/website/versioned_docs/version-mock/language-basics-functions.md new file mode 100644 index 000000000..0d8d23d8e --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-mock/language-basics-functions.md @@ -0,0 +1,23 @@ +--- +id: version-mock-language-basics-functions +title: Functions +original_id: language-basics-functions +--- + +## Defining a function + + + +```Pascal +// multiply(1, 2) = 2 +function multiply (const a : int ; const b : int) : int is + begin + const result : int = a * b ; + end with result + +// add(1, 2) = 3 +function add (const a : int ; const b : int) : int is + block { skip } with a + b +``` + + \ No newline at end of file diff --git a/gitlab-pages/website/versioned_docs/version-mock/language-basics-operators.md b/gitlab-pages/website/versioned_docs/version-mock/language-basics-operators.md new file mode 100644 index 000000000..778299c84 --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-mock/language-basics-operators.md @@ -0,0 +1,13 @@ +--- +id: version-mock-language-basics-operators +title: Operators +original_id: language-basics-operators +--- + +## Available operators + +|Michelson |Pascaligo |Description | +|--- |--- |--- | +| `SENDER` | `sender` | Address that initiated the current transaction +| `SOURCE` | `source` | Address that initiated the transaction, which triggered the current transaction. (useful e.g. when there's a transaction sent by another contract) +| `AMOUNT` | `amount` | Amount of tez sent by the transaction that invoked the contract \ No newline at end of file diff --git a/gitlab-pages/website/versioned_docs/version-mock/language-basics-variables.md b/gitlab-pages/website/versioned_docs/version-mock/language-basics-variables.md new file mode 100644 index 000000000..716de41eb --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-mock/language-basics-variables.md @@ -0,0 +1,19 @@ +--- +id: version-mock-language-basics-variables +title: Variables +original_id: language-basics-variables +--- + +## Defining a variable + + + +```Pascal +// int +const four : int = 4; + +// string +const name : string = "John Doe"; +``` + + \ No newline at end of file diff --git a/gitlab-pages/website/versioned_docs/version-mock/setup-installation.md b/gitlab-pages/website/versioned_docs/version-mock/setup-installation.md new file mode 100644 index 000000000..84862f1a0 --- /dev/null +++ b/gitlab-pages/website/versioned_docs/version-mock/setup-installation.md @@ -0,0 +1,39 @@ +--- +id: version-mock-setup-installation +title: Installation +original_id: setup-installation +--- + +There are currently two ways to get started with Ligo, both of those will allow you to use the Ligo CLI with your contracts. You can choose to use either the Docker image, or to compile & build the Ligo CLI yourself. + +## Dockerized installation (recommended) + +> 🐳 You can find instructions on how to install Docker [here](https://docs.docker.com/install/). + +Easiest way to use LIGO is through the Docker image available at [Docker Hub](https://hub.docker.com/r/ligolang/ligo). Sources for the image can be found on [Gitlab](https://gitlab.com/ligolang/ligo/blob/master/docker/Dockerfile). +You can either run the docker image yourself, or you can setup a global ligo executable as shown below. + +### Setting up a globally available `ligo` executable + +> You can install additional ligo versions by replacing `next` with the required version number + +```zsh +# next (pre-release) +curl https://gitlab.com/ligolang/ligo/blob/master/scripts/installer.sh | bash "next" + +# e.g. 1.0.0 (stable) +curl https://gitlab.com/ligolang/ligo/blob/master/scripts/installer.sh | bash "1.0.0" +``` + +**Verify your ligo installation by running:** +```zsh +ligo --help +``` + + +## Manual installation (advanced) + +For now, please refer to the steps described in the [Dockerfile](https://gitlab.com/ligolang/ligo/blob/master/docker/Dockerfile). + + + diff --git a/gitlab-pages/website/versioned_sidebars/version-mock-sidebars.json b/gitlab-pages/website/versioned_sidebars/version-mock-sidebars.json new file mode 100644 index 000000000..bcde6d71f --- /dev/null +++ b/gitlab-pages/website/versioned_sidebars/version-mock-sidebars.json @@ -0,0 +1,35 @@ +{ + "version-mock-docs": { + "Setup": [ + "version-mock-setup-installation" + ], + "Language Basics": [ + "version-mock-language-basics-variables", + "version-mock-language-basics-functions", + "version-mock-language-basics-entrypoints", + "version-mock-language-basics-operators" + ], + "API": [ + "version-mock-api-cli-commands" + ] + }, + "version-mock-contributors-docs": { + "Introduction": [ + "version-mock-contributors/origin", + "version-mock-contributors/philosophy", + "version-mock-contributors/getting-started", + "version-mock-contributors/documentation-and-releases" + ], + "Big Picture": [ + "version-mock-contributors/big-picture/overview", + "version-mock-contributors/big-picture/front-end", + "version-mock-contributors/big-picture/middle-end", + "version-mock-contributors/big-picture/back-end", + "version-mock-contributors/big-picture/vendors" + ], + "Road Map": [ + "version-mock-contributors/road-map/short-term", + "version-mock-contributors/road-map/long-term" + ] + } +} diff --git a/gitlab-pages/website/versions.json b/gitlab-pages/website/versions.json index 0637a088a..0cc8ca4be 100644 --- a/gitlab-pages/website/versions.json +++ b/gitlab-pages/website/versions.json @@ -1 +1 @@ -[] \ No newline at end of file +["mock"] \ No newline at end of file From 91c5eb694e9674e04d0a805cee11816b3b29b908 Mon Sep 17 00:00:00 2001 From: Matej Sima Date: Thu, 6 Jun 2019 16:54:08 +0200 Subject: [PATCH 05/10] Get rid of the mock version again in favor of persisting 'next' --- gitlab-pages/website/postversion.js | 2 +- .../version-mock/api-cli-commands.md | 48 ------------------- .../contributors/big-picture/back-end.md | 19 -------- .../contributors/big-picture/front-end.md | 16 ------- .../contributors/big-picture/middle-end.md | 17 ------- .../contributors/big-picture/overview.md | 17 ------- .../contributors/big-picture/vendors.md | 22 --------- .../documentation-and-releases.md | 21 -------- .../contributors/getting-started.md | 41 ---------------- .../version-mock/contributors/origin.md | 11 ----- .../version-mock/contributors/philosophy.md | 46 ------------------ .../contributors/road-map/long-term.md | 21 -------- .../contributors/road-map/short-term.md | 21 -------- .../language-basics-entrypoints.md | 45 ----------------- .../version-mock/language-basics-functions.md | 23 --------- .../version-mock/language-basics-operators.md | 13 ----- .../version-mock/language-basics-variables.md | 19 -------- .../version-mock/setup-installation.md | 39 --------------- .../version-mock-sidebars.json | 35 -------------- gitlab-pages/website/versions.json | 2 +- 20 files changed, 2 insertions(+), 476 deletions(-) delete mode 100644 gitlab-pages/website/versioned_docs/version-mock/api-cli-commands.md delete mode 100644 gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/back-end.md delete mode 100644 gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/front-end.md delete mode 100644 gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/middle-end.md delete mode 100644 gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/overview.md delete mode 100644 gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/vendors.md delete mode 100644 gitlab-pages/website/versioned_docs/version-mock/contributors/documentation-and-releases.md delete mode 100644 gitlab-pages/website/versioned_docs/version-mock/contributors/getting-started.md delete mode 100644 gitlab-pages/website/versioned_docs/version-mock/contributors/origin.md delete mode 100644 gitlab-pages/website/versioned_docs/version-mock/contributors/philosophy.md delete mode 100644 gitlab-pages/website/versioned_docs/version-mock/contributors/road-map/long-term.md delete mode 100644 gitlab-pages/website/versioned_docs/version-mock/contributors/road-map/short-term.md delete mode 100644 gitlab-pages/website/versioned_docs/version-mock/language-basics-entrypoints.md delete mode 100644 gitlab-pages/website/versioned_docs/version-mock/language-basics-functions.md delete mode 100644 gitlab-pages/website/versioned_docs/version-mock/language-basics-operators.md delete mode 100644 gitlab-pages/website/versioned_docs/version-mock/language-basics-variables.md delete mode 100644 gitlab-pages/website/versioned_docs/version-mock/setup-installation.md delete mode 100644 gitlab-pages/website/versioned_sidebars/version-mock-sidebars.json diff --git a/gitlab-pages/website/postversion.js b/gitlab-pages/website/postversion.js index b53c4a1d0..cd6c5c661 100644 --- a/gitlab-pages/website/postversion.js +++ b/gitlab-pages/website/postversion.js @@ -1 +1 @@ -require('./preversion'); \ No newline at end of file +// require('./preversion'); \ No newline at end of file diff --git a/gitlab-pages/website/versioned_docs/version-mock/api-cli-commands.md b/gitlab-pages/website/versioned_docs/version-mock/api-cli-commands.md deleted file mode 100644 index 7aa43f1c6..000000000 --- a/gitlab-pages/website/versioned_docs/version-mock/api-cli-commands.md +++ /dev/null @@ -1,48 +0,0 @@ ---- -id: version-mock-api-cli-commands -title: CLI Commands -original_id: api-cli-commands ---- - -Contracts written in Ligo can be compiled using the `ligo` executable. - - -## Compiling a contract - -Compile your contract with a specific entry point. - -```zsh -ligo compile-contract SOURCE_FILE [ENTRY_POINT] -``` - -#### Example - -```zsh -ligo compile-contract examples/counter.ligo main -``` - -## Defining the initial storage - -If your contract implements a sophisticated storage, you can compile a Ligo expression into a Michelson value quite easily. - -```zsh -ligo compile-storage SOURCE_FILE ENTRY_POINT EXPRESSION -``` - -#### Example -```zsh -ligo compile-storage examples/counter.ligo main 5 -# Outputs: 5 -``` - -## Invoking the contract with a parameter - -```zsh -ligo compile-parameter SOURCE_FILE ENTRY_POINT EXPRESSION -``` - -#### Example -```zsh -ligo compile-parameter examples/counter.ligo main "Increment(5)" -# Outputs: (Right 5) -``` \ No newline at end of file diff --git a/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/back-end.md b/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/back-end.md deleted file mode 100644 index f2833fbec..000000000 --- a/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/back-end.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -id: version-mock-back-end -title: Back End -original_id: back-end ---- - -The Back-End is the part that compiles down to Michelson. Instead of a single compilation step, it is separated in two parts. -## Transpiler and Mini_C -The Transpiler is a function that takes as input the Typed AST, and outputs expressions in a language that is basically a Michelson based on with named variables and first-class-environments. -On the one hand, there are cases in the AST like `E_if_bool` or `E_make_empty_list` that would be directly translated in Michelson like `IF {} {}` or `NIL`. -On the other hand, there are cases in the AST like `E_variable` or `E_environment_select` that specifically target the compiler. -The files of the Transpiler are in `transpiler/`, while those of Mini_c are in `mini_c/`. -## Compiler -The previous LIGO’s compilation to Michelson model was quite complicated. The current one is quite straightforward, where the environment of variables (x -> 12, y -> “foo”) is compiled as Michelson stack (12 :: foo). -It has been simplified for multiple reasons: -Having a simple model reduces its number of points of failure. -Having a simple model makes optimizing it easier. -We submitted a change to the Tezos’ protocol that actually make it more efficient. - diff --git a/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/front-end.md b/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/front-end.md deleted file mode 100644 index 03610e0d4..000000000 --- a/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/front-end.md +++ /dev/null @@ -1,16 +0,0 @@ ---- -id: version-mock-front-end -title: Front End -original_id: front-end ---- - -The Front-End is the part that deals with all syntactical matters. LIGO supports multiple Front-Ends. Each Front-End is composed of three different parts. -## Parser -A Parser is a function that takes a string of source code and outputs a structured representation of the program. This part usually uses Menhir, a parser generator compatible with OCaml. -Its files are in `parser/parser_name`. -## Concrete Syntax Tree -The CST is the aforementioned structured representation of the program. Is is structurally very close to the source code, and is mostly an intermediary there because manipulating string is not practical. -Its files are in `parser/parser_name`. -## Simplifier -A Simplifier is a function that takes a CST and outputs the corresponding Common AST. This is the actual bridge between a given syntax and LIGO. -Its files are in `simplify/parser_name`. diff --git a/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/middle-end.md b/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/middle-end.md deleted file mode 100644 index 716df9b2b..000000000 --- a/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/middle-end.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -id: version-mock-middle-end -title: Middle End -original_id: middle-end ---- - -The Middle-End is the core of LIGO. It is also composed of three parts. -## Common AST -The Common AST is the closest thing to what could be called “LIGO lang”. As such, it should be as simple as possible. Collapsing particular cases in more general constructs is encouraged. Documenting it is crucial for people who’ll write new parsers or editor support for Front-end related things. -Its files are in `ast_simplified/`, of interest is the definition of the AST itself in `ast_simplified/types.ml`. -## Type Checker -The Type Checker, among other things, checks that a given AST is valid with regard to type-safety. It also annotates expressions with their types, free-variables and local environments. -As time passes, we want to make the type-system stronger, to encode arbitrarily complex properties in an extensible manner. -Its files are in `typer/`. -## Typed AST -The Typed AST is the result of Type Checker. On top of it, we also want to define/export many features aiming at making building tools on top LIGO as easy as possible. -Its files are in `ast_typed/`, of interest is the definition of the Typed AST itself in `ast_typed/types.ml`. diff --git a/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/overview.md b/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/overview.md deleted file mode 100644 index 08125b669..000000000 --- a/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/overview.md +++ /dev/null @@ -1,17 +0,0 @@ ---- -id: version-mock-overview -title: Overview -original_id: overview ---- - -After going through the design principles and a few considerations linked to them, getting the Big Picture needs diving in technical matters. - -![LIGO Overview](/img/big-picture-overview.png) - -As shown in the Schema, LIGO’s compiler is separated in roughly 3 separate parts: - -- The Middle End. This is the core of LIGO. It defines its core data-structure (the Common AST), and its type-checking algorithm. - -- The Front End. This is the bridge between a given syntax and the Common AST. - -- The Back End. This is the bridge between the Common AST and a given compilation target. Currently, our only target is Michelson, but we’ll also target Marigold, and if Tezos moves to Web Assembly, Web Assembly. diff --git a/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/vendors.md b/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/vendors.md deleted file mode 100644 index 0fc00eaf4..000000000 --- a/gitlab-pages/website/versioned_docs/version-mock/contributors/big-picture/vendors.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -id: version-mock-vendors -title: Vendors -original_id: vendors ---- - -Next to LIGO’s main pipeline, we use some other libraries, that are in the folder `vendors`. -## ligo-utils -This, quite expectedly, defines utilities that are used in LIGO. -There are three kinds of utilities, corresponding to their dependencies. - -`tezos-utils` contain utilities that depend on some Tezos libraries. - -`proto-alpha-utils` contain utilities that depend on the compilation of some Tezos protocol. It is very big and thus can’t be compiled in JS. This is because of a dependency to this that we don’t have LIGO in the browser yet. - -`simple-utils` contain most utilities. For instance, in `simple-utils` are `X_list` and `X_option`, that extend the `List` module and the `option` type found in `Pervasives`. - -Of particular interest in `simple-utils` is `trace.ml`, a module used pervasively in LIGO’s code-base. It deals with exceptions (and soon enough debugging annotations) in a functional manner. It offers a lot of utilities to build, combine and propagate exceptions. Given it’s used everywhere, that it relies on some advanced features of OCaml (higher order functions, ppx preprocessing) and that it exposes **a lot** of functions, it’s a good idea to look at this file’s documentation. -## tezos-modded -`tezos-modded` is a modded version of Tezos. There are modifications in it that are quite useful (exposing more functions from the protocol, giving more options to functions already defined), but not integrated yet. -It should in the end be integrated into the Tezos protocol, but until then, we use this. - diff --git a/gitlab-pages/website/versioned_docs/version-mock/contributors/documentation-and-releases.md b/gitlab-pages/website/versioned_docs/version-mock/contributors/documentation-and-releases.md deleted file mode 100644 index 63c9b9f0d..000000000 --- a/gitlab-pages/website/versioned_docs/version-mock/contributors/documentation-and-releases.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -id: version-mock-documentation-and-releases -title: Documentation and releases -original_id: documentation-and-releases ---- - - -## Documentation - -In case you'd like to contribute to the docs, you can find them at [`gitlab-pages/docs`]() in their raw markdown form. -Deployment of the docs/website for LIGO is taken care of within the CI, from `dev` and `master` branches. - -## Releases & versioning - -### Development releases (next) - -Development releases of Ligo are tagged as `next` and are built with each commit to the `dev` branch. Both the docker image & the website are published automatically. - -### Stable releases - -Releases tagged with version numbers `x.x.x` are built manually, both docs & the docker image. While deployment of the website is handled by the CI. diff --git a/gitlab-pages/website/versioned_docs/version-mock/contributors/getting-started.md b/gitlab-pages/website/versioned_docs/version-mock/contributors/getting-started.md deleted file mode 100644 index a8b9e08c6..000000000 --- a/gitlab-pages/website/versioned_docs/version-mock/contributors/getting-started.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -id: version-mock-getting-started -title: Getting started -original_id: getting-started ---- - -## Where -As we’ve seen, LIGO is big, as such, it is easier to start focus on a specific part of LIGO. As very vague suggestions: -If you want to immediately see the result of your contributions, you might want to start with the Front-End. This is what most people will directly see of LIGO. -If you want to get into Programming Language Theory, you might want to start with the Middle-End. This is where the Type System and the Language Definition are (the closest thing so far that you’ll find in a research paper). -If you want to get into the nitty gritty details of compiling to special targets, you’ll want to focus on the Back-End. -If you want to develop tooling on top of LIGO (editor integration, for instance), you’ll want to look at `Ast_typed/types.ml`. This is where most information that is relevant to devs will be (for now). -If you really want to get a grasp of the whole pipeline, search for issues tagged with “Everything”, they’ll have you look at multiple parts of the code base. -## What -Likely, the first issues will be about: -Adding tests -Extending the languages by adding new operators -Adding tests -Refactoring -Writing documentation and tutorials for users -Adding tests -Writing internal documentation when you understand a part of the code base ->Tests are **really** important, we don’t have lots of them, and mostly regression ones. This can’t be stressed enough. Some features are missing not because we can’t add them, but because we don’t know so as no tests tell us they are missing. -## How -Issues will be added to the Gitlab, tagged with On-boarding and Front-End / Middle-End / Back-End / Everything. If you try to tackle one issue, and you have **any** problem, please tell us, by creating a new Gitlab issue, contacting us on Riot, Discord or even by mail! Problems might include: -Installing the repository or the tools needed to work on it -OCaml weirdness -Understanding undocumented parts of the code base -Documented parts of the code base too -**Anything really** - ---- - -## FAQ -### I don’t know much about OCaml, where should I start? What should I have in mind? -I’d suggesting going through Real World OCaml to get a feel for the language, to know what are its features, and to know what to Google when you’re lost. -Beyond that, I’d say, start hacking! Either on LIGO’s code base, or on any personal project. -There is a Discord server if you want real-time help (which makes things go way faster than waiting for an answer on stackoverflow or looking mindlessly at the monitor). -### I want to add [X] to LIGO! Where should I begin? -Trying to add a new feature from scratch instead of building upon one can be quite complicated. However, if you’re motivated, contact us! We’ll tell you what we see as the most likely plan to get the result you want to achieve. - diff --git a/gitlab-pages/website/versioned_docs/version-mock/contributors/origin.md b/gitlab-pages/website/versioned_docs/version-mock/contributors/origin.md deleted file mode 100644 index ebf7c3402..000000000 --- a/gitlab-pages/website/versioned_docs/version-mock/contributors/origin.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -id: version-mock-origin -title: Origin -original_id: origin ---- - -LIGO is a programming language that aims to provide developers with an uncomplicated and safer way to implement smart-contracts. LIGO is currently being implemented for the Tezos blockchain and as a result, it compiles down to Michelson - the native smart-contract language of Tezos. - -> Smart-contracts are programs that run within a blockchain network. - -LIGO was initially meant to be a language for developing Marigold, on top of a hacky framework called Meta-Michelson. However, due to the attention received by the Tezos community, a decision has been put into action to develop LIGO as a standalone language that will support Tezos directly as well. \ No newline at end of file diff --git a/gitlab-pages/website/versioned_docs/version-mock/contributors/philosophy.md b/gitlab-pages/website/versioned_docs/version-mock/contributors/philosophy.md deleted file mode 100644 index 5f859f0d8..000000000 --- a/gitlab-pages/website/versioned_docs/version-mock/contributors/philosophy.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -id: version-mock-philosophy -title: Philosophy -original_id: philosophy ---- - -To understand LIGO’s design choices, it’s important to get its philosophy. There are two main concerns that we have in mind when building LIGO. - - - -## Safety -Once a smart-contract is deployed, it will likely be impossible to change it. You must get it right on the first try, and LIGO should help as much as possible. There are multiple ways to make LIGO a safer language for smart-contracts. - -### Automated Testing -Automated Testing is the process through which a program will run some other program, and check that this other program behaves correctly. -There already is a testing library for LIGO programs written in OCaml that is used to test LIGO itself. Making it accessible to users will greatly improve safety. A way to do so would be to make it accessible from within LIGO. - -### Static Analysis -Static analysis is the process of having a program analyze another one. -For instance, type systems are a kind of static analysis through which it is possible to find lots of bugs. There is already a fairly simple type system in LIGO, and we plan to make it much stronger. - -### Conciseness -Writing less code gives you less room to introduce errors and that's why LIGO encourages writing lean rather than chunky smart-contracts. - ---- - -## Ergonomics -Having an ergonomic product is crucial on multiple levels: -Making features easily accessible ensures they’ll actually get used. -Not wasting users time on idiosyncrasies frees more time for making contracts safer or building apps. -Keeping users in a Flow state makes it possible to introduce more complex features in the language. -There are multiple ways to improve ergonomics. - -### The Language -LIGO should contain as few surprises as possible. This is usually known as the principle of least surprise. - -Most programmers who will use LIGO have already spent a lot of time learning to develop in an existing language, with its own set of conventions and expectations. These expectations are often the most important to accommodate. This is why C-style syntaxes are especially popular (e.g. JavaScript), C-style is well known and new languages want to take advantage of that familiarity. Therefore as an extension of the principle of least surprise, LIGO supports more than one syntax. The least surprising language for a new developer is the one that they have already learned how to use. It’s probably not practical to replicate the syntax of every programming language, so LIGO takes the approach of replicating the structure used by languages from a particular paradigm. - -It is packaged in a Docker container, so that no particular installation instructions are required. - -### Editor Support -Without editor support, a lot of manipulations are very cumbersome. Checking for errors, testing, examining code, refactoring code, etc. This is why there is ongoing work on editor support, starting with highlighting and code-folding. - -### Docs -Docs include documentation of the languages, tutorials, as well as examples and design patterns. -We’re a long way from there. But having extensive docs is part of our goals. \ No newline at end of file diff --git a/gitlab-pages/website/versioned_docs/version-mock/contributors/road-map/long-term.md b/gitlab-pages/website/versioned_docs/version-mock/contributors/road-map/long-term.md deleted file mode 100644 index 00e85be19..000000000 --- a/gitlab-pages/website/versioned_docs/version-mock/contributors/road-map/long-term.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -id: version-mock-long-term -title: Longer term -original_id: long-term ---- - -Soon enough, the Schema for the front-end will look like this: - -![LIGO Overview](/img/generic-front-end.png) - -Basically, as we support more syntaxes (up to half a dozen), we’ll have a bigger need for a unified representation and generation of the helpers around it. -For instance: -Parsers. So far, parsers are generated by LR grammars. LR grammars have a steep learning curve, regularly making not worth it for someone to learn the whole formalism to extend a given grammar with a few cases. Generating those LR Grammars would thus save a lot of time. -Displayers. The idea is that if you can parse and display code in a given syntax, it becomes much easier to have a translator between each syntax. So that not only it becomes possible for users to write code in their favorite syntax, but also to only read code in their favorite syntax. -BNFs. BNF grammars are a common formalism to represent grammars. They are understood by many tools, and are an easy way to document a given syntax. -## Super Type System -Soon enough, the Schema for the middle-end will look like this: -![LIGO Overview](/img/super-type-system.png) -Basically, this schema shows that the Back-End will stop being the main consumer of the Typed AST, and the External World will in its stead. -As such, annotating the AST with quality information, documenting it and exposing the libraries that produced the information in the first place will be paramount. -The imagined type-system so far is a mixture of MLF, extensible data-types and Algebraic Effects. \ No newline at end of file diff --git a/gitlab-pages/website/versioned_docs/version-mock/contributors/road-map/short-term.md b/gitlab-pages/website/versioned_docs/version-mock/contributors/road-map/short-term.md deleted file mode 100644 index 4de1579d7..000000000 --- a/gitlab-pages/website/versioned_docs/version-mock/contributors/road-map/short-term.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -id: version-mock-short-term -title: Short term -original_id: short-term ---- - -## Documentation and Testing -We lack documentation and tests. Top priority. -Tests are needed at multiple levels: -Unit tests. Most utility functions should be tested individually. -Interface tests. Parts of the pipeline (Typer, Transpiler-Compiler, etc.) should be tested as black boxes. -Integration tests. Typical user scenarios, as interacted with the CLI, should be tested. -## Exposing Features -Many features have already been developed or nearly developed, and mostly need to be shown some attention, and then be exposed to the outside world, for instance: -Testing LIGO code -Step-by-step interpreter -LIGO in the browser -Propagating source locations for error messages -Dry-running a contract -## Refactoring -For the longer-term, it’s crucial to refactor big parts of the code base. This is needed to lower the complexity of the code base, so that it’s easier both for everyone (including API consumers) to interact with it. diff --git a/gitlab-pages/website/versioned_docs/version-mock/language-basics-entrypoints.md b/gitlab-pages/website/versioned_docs/version-mock/language-basics-entrypoints.md deleted file mode 100644 index b645fbbbb..000000000 --- a/gitlab-pages/website/versioned_docs/version-mock/language-basics-entrypoints.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -id: version-mock-language-basics-entrypoints -title: Entrypoints -original_id: language-basics-entrypoints ---- - -## Defining an entry point - - - -```Pascal -function main (const p : int ; const s : int) : (list(operation) * unit) is - block {skip} with ((nil : list(operation)), s + 1) -``` - - -## Multiple entry points - -Multiple entrypoints are currently not supported in Michelson, however with Ligo, you can work that around by using variants. - - - -```Pascal -// variant defining pseudo multi-entrypoint actions -type action is -| Increment of int -| Decrement of int - -function add (const a : int ; const b : int) : int is - block { skip } with a + b - -function subtract (const a : int ; const b : int) : int is - block { skip } with a - b - -// real entrypoint that re-routes the flow based on the action provided -function main (const p : action ; const s : int) : (list(operation) * int) is - block {skip} with ((nil : list(operation)), - case p of - | Increment n -> add(s, n) - | Decrement n -> subtract(s, n) - end) -``` - - - \ No newline at end of file diff --git a/gitlab-pages/website/versioned_docs/version-mock/language-basics-functions.md b/gitlab-pages/website/versioned_docs/version-mock/language-basics-functions.md deleted file mode 100644 index 0d8d23d8e..000000000 --- a/gitlab-pages/website/versioned_docs/version-mock/language-basics-functions.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -id: version-mock-language-basics-functions -title: Functions -original_id: language-basics-functions ---- - -## Defining a function - - - -```Pascal -// multiply(1, 2) = 2 -function multiply (const a : int ; const b : int) : int is - begin - const result : int = a * b ; - end with result - -// add(1, 2) = 3 -function add (const a : int ; const b : int) : int is - block { skip } with a + b -``` - - \ No newline at end of file diff --git a/gitlab-pages/website/versioned_docs/version-mock/language-basics-operators.md b/gitlab-pages/website/versioned_docs/version-mock/language-basics-operators.md deleted file mode 100644 index 778299c84..000000000 --- a/gitlab-pages/website/versioned_docs/version-mock/language-basics-operators.md +++ /dev/null @@ -1,13 +0,0 @@ ---- -id: version-mock-language-basics-operators -title: Operators -original_id: language-basics-operators ---- - -## Available operators - -|Michelson |Pascaligo |Description | -|--- |--- |--- | -| `SENDER` | `sender` | Address that initiated the current transaction -| `SOURCE` | `source` | Address that initiated the transaction, which triggered the current transaction. (useful e.g. when there's a transaction sent by another contract) -| `AMOUNT` | `amount` | Amount of tez sent by the transaction that invoked the contract \ No newline at end of file diff --git a/gitlab-pages/website/versioned_docs/version-mock/language-basics-variables.md b/gitlab-pages/website/versioned_docs/version-mock/language-basics-variables.md deleted file mode 100644 index 716de41eb..000000000 --- a/gitlab-pages/website/versioned_docs/version-mock/language-basics-variables.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -id: version-mock-language-basics-variables -title: Variables -original_id: language-basics-variables ---- - -## Defining a variable - - - -```Pascal -// int -const four : int = 4; - -// string -const name : string = "John Doe"; -``` - - \ No newline at end of file diff --git a/gitlab-pages/website/versioned_docs/version-mock/setup-installation.md b/gitlab-pages/website/versioned_docs/version-mock/setup-installation.md deleted file mode 100644 index 84862f1a0..000000000 --- a/gitlab-pages/website/versioned_docs/version-mock/setup-installation.md +++ /dev/null @@ -1,39 +0,0 @@ ---- -id: version-mock-setup-installation -title: Installation -original_id: setup-installation ---- - -There are currently two ways to get started with Ligo, both of those will allow you to use the Ligo CLI with your contracts. You can choose to use either the Docker image, or to compile & build the Ligo CLI yourself. - -## Dockerized installation (recommended) - -> 🐳 You can find instructions on how to install Docker [here](https://docs.docker.com/install/). - -Easiest way to use LIGO is through the Docker image available at [Docker Hub](https://hub.docker.com/r/ligolang/ligo). Sources for the image can be found on [Gitlab](https://gitlab.com/ligolang/ligo/blob/master/docker/Dockerfile). -You can either run the docker image yourself, or you can setup a global ligo executable as shown below. - -### Setting up a globally available `ligo` executable - -> You can install additional ligo versions by replacing `next` with the required version number - -```zsh -# next (pre-release) -curl https://gitlab.com/ligolang/ligo/blob/master/scripts/installer.sh | bash "next" - -# e.g. 1.0.0 (stable) -curl https://gitlab.com/ligolang/ligo/blob/master/scripts/installer.sh | bash "1.0.0" -``` - -**Verify your ligo installation by running:** -```zsh -ligo --help -``` - - -## Manual installation (advanced) - -For now, please refer to the steps described in the [Dockerfile](https://gitlab.com/ligolang/ligo/blob/master/docker/Dockerfile). - - - diff --git a/gitlab-pages/website/versioned_sidebars/version-mock-sidebars.json b/gitlab-pages/website/versioned_sidebars/version-mock-sidebars.json deleted file mode 100644 index bcde6d71f..000000000 --- a/gitlab-pages/website/versioned_sidebars/version-mock-sidebars.json +++ /dev/null @@ -1,35 +0,0 @@ -{ - "version-mock-docs": { - "Setup": [ - "version-mock-setup-installation" - ], - "Language Basics": [ - "version-mock-language-basics-variables", - "version-mock-language-basics-functions", - "version-mock-language-basics-entrypoints", - "version-mock-language-basics-operators" - ], - "API": [ - "version-mock-api-cli-commands" - ] - }, - "version-mock-contributors-docs": { - "Introduction": [ - "version-mock-contributors/origin", - "version-mock-contributors/philosophy", - "version-mock-contributors/getting-started", - "version-mock-contributors/documentation-and-releases" - ], - "Big Picture": [ - "version-mock-contributors/big-picture/overview", - "version-mock-contributors/big-picture/front-end", - "version-mock-contributors/big-picture/middle-end", - "version-mock-contributors/big-picture/back-end", - "version-mock-contributors/big-picture/vendors" - ], - "Road Map": [ - "version-mock-contributors/road-map/short-term", - "version-mock-contributors/road-map/long-term" - ] - } -} diff --git a/gitlab-pages/website/versions.json b/gitlab-pages/website/versions.json index 0cc8ca4be..c68311062 100644 --- a/gitlab-pages/website/versions.json +++ b/gitlab-pages/website/versions.json @@ -1 +1 @@ -["mock"] \ No newline at end of file +["next"] \ No newline at end of file From 35cd5791a54b54aa433723e0b8eca33a80486b1e Mon Sep 17 00:00:00 2001 From: Matej Sima Date: Thu, 6 Jun 2019 16:59:05 +0200 Subject: [PATCH 06/10] Fix website build errror --- gitlab-pages/website/pages/en/index.js | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/gitlab-pages/website/pages/en/index.js b/gitlab-pages/website/pages/en/index.js index 6836c9ff1..e7e9210f4 100644 --- a/gitlab-pages/website/pages/en/index.js +++ b/gitlab-pages/website/pages/en/index.js @@ -26,22 +26,22 @@ class HomeSplash extends React.Component {
-
-
-