From 85799cc4ac638d24c107ec061b8e942645af5049 Mon Sep 17 00:00:00 2001 From: collodi Date: Wed, 18 Jan 2023 23:39:00 +0900 Subject: [PATCH] Installation Guide --- README.md | 2 +- _build/html/README.html | 13 +- _build/html/_sources/README.md | 12 +- _build/html/_sources/getting-started.md | 81 ++++++++++ _build/html/_sources/markdown-notebooks.ipynb | 6 +- _build/html/getting-started.html | 146 ++++++++++++++++++ _build/html/objects.inv | Bin 470 -> 469 bytes _build/html/searchindex.js | 2 +- getting-started.md | 81 ++++++++++ 9 files changed, 326 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 07cd805..be63b33 100644 --- a/README.md +++ b/README.md @@ -7,4 +7,4 @@ 2. write contents in a new file (e.g. `chapter1.md`). 3. add an entry in `_toc.yml` (e.g. `- file: markdown-notebooks`) 4. Make a new PR to merge into the `main` branch. -5. (for publisher/administrator) after the working branch is merged, execute `jupyter-book build .` and then `ghp-import -n -p -f _build/html`. `ghp-import` will automatically push all the changes into the `gh-pages` branch. +5. (for publisher/administrator) after the working branch is merged, execute `jupyter-book build .` and then `ghp-import -n -p -f _build/html`. `ghp-import` will automatically push all the changes into the `gh-pages` branch. GitHub Actions will do the rest. diff --git a/_build/html/README.html b/_build/html/README.html index a4b48f4..2f978a6 100644 --- a/_build/html/README.html +++ b/_build/html/README.html @@ -6,7 +6,7 @@ - quisp-textbook — QuISP Textbook + QuISP Textbook — QuISP Textbook @@ -323,7 +323,7 @@

QuISP Textbook

-

quisp-textbook

+

QuISP Textbook

@@ -349,15 +349,16 @@

Contents

-

quisp-textbook#

+

QuISP Textbook#

cover

instruction to edit quisp-textbook#

    -

  1. write contents in a new file (e.g. chapter1.md)

    2. +

  2. Create a new branch for your work, and checkout to that branch

    3. +

  3. write contents in a new file (e.g. chapter1.md).

  4. add an entry in _toc.yml (e.g. - file: markdown-notebooks)

    5. -

  5. in quisp-textbook directory, run jupyter-book build .

    6. -

  6. open _build/html/index.html to check the generated textbook

    7. +

  7. Make a new PR to merge into the main branch.

    8. +

  8. (for publisher/administrator) after the working branch is merged, execute jupyter-book build . and then ghp-import -n -p -f _build/html. ghp-import will automatically push all the changes into the gh-pages branch. GitHub Actions will do the rest.

diff --git a/_build/html/_sources/README.md b/_build/html/_sources/README.md index 2a996e6..be63b33 100644 --- a/_build/html/_sources/README.md +++ b/_build/html/_sources/README.md @@ -1,10 +1,10 @@ -# quisp-textbook +# QuISP Textbook ![cover](cover.jpg "Cover") ## instruction to edit quisp-textbook - -1. write contents in a new file (e.g. `chapter1.md`) -2. add an entry in `_toc.yml` (e.g. `- file: markdown-notebooks`) -3. in quisp-textbook directory, run `jupyter-book build .` -4. `open _build/html/index.html` to check the generated textbook +1. Create a new branch for your work, and checkout to that branch +2. write contents in a new file (e.g. `chapter1.md`). +3. add an entry in `_toc.yml` (e.g. `- file: markdown-notebooks`) +4. Make a new PR to merge into the `main` branch. +5. (for publisher/administrator) after the working branch is merged, execute `jupyter-book build .` and then `ghp-import -n -p -f _build/html`. `ghp-import` will automatically push all the changes into the `gh-pages` branch. GitHub Actions will do the rest. diff --git a/_build/html/_sources/getting-started.md b/_build/html/_sources/getting-started.md index bad5562..7366a00 100644 --- a/_build/html/_sources/getting-started.md +++ b/_build/html/_sources/getting-started.md @@ -1 +1,82 @@ # Getting Started + +Okay, enough talks. Now let's see how quisp is working with our bare eyes. We have to build QuISP in our machine for that. + +> :warning: **Building the software from source** might look awkward to some developers with interpreter-based languages (such as Python, Lua, JS...). We are going to add the software build section to the textbook, explaining the architecture of GNU `make` and the concept of `makemake` we are using with OMNeT++. Don't switch the channel! For now, you can follow our manual to get the correct result. + +## Installation + +### Recommended Environment +- Docker with at least 6GB of allocated RAM (you can change that in Docker Desktop Settings) +...and that's it! + +The following procedures were confirmed working on the MacOS Catalina (10.15.3) and Mojave(10.14). + +### TL;DR +- Install brew, docker, XQuartz and socat with `sh docker_tools.sh` +- clone quisp +- `docker pull ghcr.io/sfc-aqua/quisp` +- Run docker with `sh docker_run.sh` +- Run `omnetpp` command on the docker container + +--- + +### Automated way + +1. Open your terminal and run + +```zsh +$ git clone https://github.com/sfc-aqua/quisp.git +``` + +You can download quisp from github. +Enter quisp with `cd quisp` +2. Run shell script + +```zsh +$ sh docker_tools.sh +``` + +After you have successfully installed the related tools, please reboot your laptop. (Maybe just rebooting your terminal is enough.) + +3. Build docker container + +Open terminal and run, + +```zsh +$ docker pull ghcr.io/sfc-aqua/quisp +``` + +A docker image called quisp should have been created. You can check with the command `docker images`. + +4. Run docker container + +OK, now you can enter the container. + +```zsh +$ sh docker_run.sh +``` + +If this error pops up, +```zsh +docker_run.sh: line 15: xhost: command not found +docker_run.sh: line 15: xterm: command not found +``` +add `/usr/X11/bin` (might vary) to your path + +5. Try quisp! + +If all of the processing completed successfully, you should see + +```zsh +quisp:/root/quisp$ +``` + +Open omnet with + +```zsh +quisp:/root/quisp$ omnetpp +``` + +Enjoy quisp! + diff --git a/_build/html/_sources/markdown-notebooks.ipynb b/_build/html/_sources/markdown-notebooks.ipynb index fa92031..d782d63 100644 --- a/_build/html/_sources/markdown-notebooks.ipynb +++ b/_build/html/_sources/markdown-notebooks.ipynb @@ -2,7 +2,7 @@ "cells": [ { "cell_type": "markdown", - "id": "abaca5fb", + "id": "ec9d0c81", "metadata": {}, "source": [ "# Notebooks with MyST Markdown\n", @@ -19,7 +19,7 @@ { "cell_type": "code", "execution_count": 1, - "id": "cc40d43e", + "id": "73c38ddc", "metadata": {}, "outputs": [ { @@ -36,7 +36,7 @@ }, { "cell_type": "markdown", - "id": "d6433c54", + "id": "9b677916", "metadata": {}, "source": [ "When your book is built, the contents of any `{code-cell}` blocks will be\n", diff --git a/_build/html/getting-started.html b/_build/html/getting-started.html index 028c347..3995ce5 100644 --- a/_build/html/getting-started.html +++ b/_build/html/getting-started.html @@ -288,12 +288,53 @@

QuISP Textbook

+
+
+ Contents +
+
@@ -305,6 +346,36 @@

Getting Started

@@ -314,6 +385,81 @@

Getting Started

Getting Started#

+

Okay, enough talks. Now let’s see how quisp is working with our bare eyes. We have to build QuISP in our machine for that.

+
+

:warning: Building the software from source might look awkward to some developers with interpreter-based languages (such as Python, Lua, JS…). We are going to add the software build section to the textbook, explaining the architecture of GNU make and the concept of makemake we are using with OMNeT++. Don’t switch the channel! For now, you can follow our manual to get the correct result.

+
+
+

Installation#

+ +
+

TL;DR#

+
    +

  • Install brew, docker, XQuartz and socat with sh docker_tools.sh

    • +

  • clone quisp

    • +

  • docker pull ghcr.io/sfc-aqua/quisp

    • +

  • Run docker with sh docker_run.sh

    • +

  • Run omnetpp command on the docker container

    • +
+
+
+
+

Automated way#

+
    +

  1. Open your terminal and run

    2. +
+
$ git clone https://github.com/sfc-aqua/quisp.git
+
+
+

You can download quisp from github. +Enter quisp with cd quisp +2. Run shell script

+
$ sh docker_tools.sh
+
+
+

After you have successfully installed the related tools, please reboot your laptop. (Maybe just rebooting your terminal is enough.)

+
    +

  1. Build docker container

    2. +
+

Open terminal and run,

+
$ docker pull ghcr.io/sfc-aqua/quisp
+
+
+

A docker image called quisp should have been created. You can check with the command docker images.

+
    +

  1. Run docker container

    2. +
+

OK, now you can enter the container.

+
$ sh docker_run.sh
+
+
+

If this error pops up,

+
docker_run.sh: line 15: xhost: command not found
+docker_run.sh: line 15: xterm: command not found
+
+
+

add /usr/X11/bin (might vary) to your path

+
    +

  1. Try quisp!

    2. +
+

If all of the processing completed successfully, you should see

+
quisp:/root/quisp$
+
+
+

Open omnet with

+
quisp:/root/quisp$ omnetpp
+
+
+

Enjoy quisp!

+
+