Skip to content
New issue

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

Sign up for GitHub

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

Already on GitHub? Sign in to your account

Update README #152

Merged
merged 10 commits into from
Mar 10, 2023
+39 −64
Merged

Update README #152

Changes from 8 commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
64c24f1
update README.md
mraszyk Jul 8, 2022
a4d39d3
update port in README
mraszyk Jul 14, 2022
1312269
update README
mraszyk Jul 15, 2022
05122ad
Merge branch 'master' into mraszyk/readme
mraszyk Mar 10, 2023
6601789
dfx network config
mraszyk Mar 10, 2023
053471d
update README
mraszyk Mar 10, 2023
8a02e2f
typo
mraszyk Mar 10, 2023
7760c42
listen-port
mraszyk Mar 10, 2023
2409403
Update README.md
mraszyk Mar 10, 2023
f39c17f
Update README.md
mraszyk Mar 10, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
104 changes: 40 additions & 64 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,15 +1,15 @@
The Internet Computer Haskell Toolkit
=====================================

This repository contains a bunch of Internet-Computer related code written to support the following use cases:
This repository contains a bunch of Internet Computer related code written to support the following use cases:

ic-ref: a IC reference implementation
-------------------------------------

The `ic-ref` binary is a partial implementation of the external interface of
the Internet Computer, as specified in the [Interface Spec].

[Interface Spec]: https://sdk.dfinity.org/docs/interface-spec/index.html
[Interface Spec]: https://internetcomputer.org/docs/current/references/ic-interface-spec

The goals of the reference implementation are

Expand Down Expand Up @@ -50,7 +50,7 @@ run their canisters locally. This adds additional goals:
help debug canisters.

Should these goals eventually conflict with the goals for a reference
implementation, e.g. becauese they impose complexity that is not easy to
implementation, e.g. because they impose complexity that is not easy to
contain in auxillary modules, a project split might be considered.

There are also explicit non-goals to keep in mind:
Expand Down Expand Up @@ -97,7 +97,7 @@ To achieve these goals, the following design decisions are made:
is “executable pseudo-code”. The use of advanced langauge features or non-idiomatic
code that _help_ readability are encouraged.

Examples: `IC.Ref`, `IC.Canister.Impl`, `IC.HTTP.RequestId`
Examples: `IC.Ref`, `IC.Canister.Imp`, `IC.HTTP.RequestId`

- is a plumbing module that handles some technical aspect, and pave the way
for the simplicity in the previously mentioned modules. It is expected
Expand All @@ -110,17 +110,34 @@ To achieve these goals, the following design decisions are made:

### Usage

The `ic-ref` program starts a webserver at `http://0.0.0.0:8001/` that implements the
Internet Computer interface, and can be used with `dfx --client http://0.0.0.0:8001/`.
The `ic-ref` program (invoked with `--listen-port 8080`) starts a webserver
at `http://localhost:8080/` that implements the Internet Computer interface,
and can be used with `dfx` by updating your dfx configuration:
```console
$ cat ~/.config/dfx/networks.json
{
"local": {
"bind": "127.0.0.1:8080",
"type": "ephemeral",
"replica": {
"subnet_type": "system"
}
}
}
```

If you point your browser to `http://0.0.0.0:8001/` you get the evolution of
the IC state as JSON. Recommended to use Firefox, as it provides a nice UI for
browsing JSON.
If you point your browser to `http://localhost:8080/` you get the evolution of
the IC state as JSON. We recommended to use Firefox, as it provides a nice UI for
browsing JSON. Note that the IC state can become quite large and the browser might be
slow to load it.

If the `--state-file FILE` argument is given, `ic-ref` will persist its state
in this file. Note that if that file cannot be read (e.g. because it is from
an incompatible version of `ic-ref`), starting `ic-ref` will fail.

Do not forget to clean up the directory `.dfx/` in your development tree before
starting `ic-ref` from a fresh state, i.e., if not providing `--state-file FILE`.


ic-ref-test: An acceptance test suite
-------------------------------------
Expand All @@ -132,7 +149,16 @@ functional tests against it.

### Usage

Pass `--endpoint http://localhost:8080/` to run against a specific node.
Before running `ic-ref-test`, make sure you have built the universal canister
(using `nix-shell`):
```
cd universal-canister
nix-shell --command 'cargo build --target wasm32-unknown-unknown --release'
```
mraszyk marked this conversation as resolved.
Show resolved Hide resolved
or reset the symbolic link in `test-data/universal_canister.wasm`
to the universal canister's Wasm.

Pass `--endpoint http://localhost:8080/` to run against a specific IC instance.

With the `-p pattern` flag you can select individual tests; those whose names
contain the pattern. See https://github.com/feuerbach/tasty#patterns for
Expand Down Expand Up @@ -161,41 +187,14 @@ calculates its request id.
ic-hs: The library
------------------

The modules of the above tools can be used for other purposes. In that sense, the whole project is one big Haskell library that can be used in quick experiments, in the Haskell REPL, or as a libary to build other tools (e.g. a test framework for canisters as [in the case of the Internet Identity](https://github.com/dfinity/internet-identity/tree/main/backend-tests)).


To use the Haskell REPL to interact with the internet computer, follow this pattern:
```
~/dfinity/ic-hs $ cabal repl ic-ref-test
…
Ok, 27 modules loaded.
*Main> :m + *IC.Test.Spec
*IC.Test.Spec *Main> :set -XOverloadedStrings
*IC.Test.Spec *Main> R r <- connect "http://localhost:34677/"
Fetching endpoint status from "http://localhost:34677"...
Spec version tested: 0.14.0
Spec version claimed: 0.14.0
*IC.Test.Spec *Main> r $ install noop
"\NUL\NUL\NUL\NUL\NUL\NUL\NUL\SOH\SOH\SOH"
*IC.Test.Spec *Main> cid1 <- r $ install noop
*IC.Test.Spec *Main> prettyBlob cid1
"00000000000000020101"
*IC.Test.Spec *Main> r $ call cid1 (setGlobal "Foo" >>> replyData "Hello")
"Hello"
*IC.Test.Spec *Main> r $ query cid1 (replyData getGlobal)
"Foo"
```

It’s necessary to wrap all lines with the `r $ …` for now; this sets the
endpoint parameter.

The modules of the above tools can be used for other purposes. In that sense, the whole project is one big Haskell library that can be used in quick experiments or as a libary to build other tools (e.g. a test framework for developer tools as [in the case of DFX](https://github.com/dfinity/sdk/blob/master/.github/workflows/e2e.yml)).

Continuous Integration
----------------------

We use GitHub Actions to trigger builds of the jobs defined in `./default.nix`. However the builds themselves are run on the [nixbuild.net](https://nixbuild.net/) service since it provides more capacity and is more efficient than GitHub runners.

Please use the artifacts produced by GitHub Actions and nixbuild.net at your own risk or consider building independently from source.
Please use the artifacts produced by GitHub Actions and [nixbuild.net](https://nixbuild.net/) at your own risk or consider building independently from source.
mraszyk marked this conversation as resolved.
Show resolved Hide resolved


Running
Expand All @@ -213,7 +212,7 @@ following commands in this directory:

You can also pass arguments, e.g.

nix run -f . -c ic-ref-test --endpoint http://0.0.0.0:8080 -p 'WebAuthn'
nix run -f . -c ic-ref-test --endpoint http://localhost:8080 -p 'WebAuthn'


Developing on ic-ref
Expand All @@ -223,21 +222,6 @@ Running `nix-shell` gives you an environment that allows you to build the
project using `cabal build`. You can also run `cabal run ic-ref` etc. to run it
directly from source.

One possible workflow is to run

ghcid -c 'cabal repl ic-ref' -T Main.main

which will run `ic-ref` and restart upon file changes. Similarly


For `ic-ref-test`, before running it, you make sure you have built the universal canister.

The symbolic link in `test-data/universal-canister.wasm` points to the
build output produced by

cd universal-canister
nix-shell --command 'cargo build --target wasm32-unknown-unknown --release'

You can now run the test suite from the top-level directory with

cabal run ic-ref-test
mraszyk marked this conversation as resolved.
Show resolved Hide resolved
Expand All @@ -249,14 +233,6 @@ The `-p` flag, i.e.
allows you can run tests selectively (i.e. only those whose name include
“upgrade”).

Again, you can use `ghcid` to run the test suite upon file changes:

ghcid -c 'cabal repl ic-ref-test' -T Main.main

and you can flags with

ghcid -c 'cabal repl ic-ref-test' -T Main.main --setup ':set args --rerun -p "query call"'

Versioning
----------

Expand All @@ -265,7 +241,7 @@ implement, e.g. `0.18.0`. Should older major released require additional
commits (bugfixes, or additional minor releases) that cannot be created on
`master`, a `release-0.18` branch would be created.

[Interface Spec]: https://sdk.dfinity.org/docs/interface-spec/index.html
[Interface Spec]: https://internetcomputer.org/docs/current/references/ic-interface-spec

Updating Haskell Packages
-------------------------
Expand Down