From 85bc00c8ec3be247e2a4962d7937cb03737ccb19 Mon Sep 17 00:00:00 2001
From: carp-lang <bot@carp-lang.github.io>
Date: Tue, 24 Nov 2020 05:48:03 +0000
Subject: [PATCH] Docs generated from: docs: A document about running code
 (#1013)

* docs: A document about running code

* fix: Tweaks

* docs: More information about running code

Co-authored-by: Erik Svedang <erik@Eriks-iMac.local>
---
 HowToRunCode.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++
 Manual.md       |  3 ++-
 2 files changed, 59 insertions(+), 1 deletion(-)
 create mode 100644 HowToRunCode.md

diff --git a/HowToRunCode.md b/HowToRunCode.md
new file mode 100644
index 0000000..cbc0222
--- /dev/null
+++ b/HowToRunCode.md
@@ -0,0 +1,57 @@
+# How to run code
+
+This document is aimed at people just starting out with Carp, in particular if you want to try out the [examples](../examples).
+
+## Prerequisites
+
+Make sure that you have [installed the Carp compiler and its dependencies](Install.md) and that you can start it without any error messages. Here's how it should look:
+
+```bash
+$ carp
+Welcome to Carp X.Y.Z
+This is free software with ABSOLUTELY NO WARRANTY.
+Evaluate (help) for more information.
+鲤
+```
+
+The `鲤` character on the last line is the [REPL](https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop) prompt, it means that Carp is waiting for you to enter a command.
+
+## Running code from the REPL
+
+You can load some code with:
+
+```bash
+鲤 (load "some_file.carp")
+```
+
+The path to the file should be relative to where you started `carp` (or in your [search-path](Libraries.md) path).
+It is also possible to paste a block of code (even multiple top-level expressions) into the REPL.
+
+To build and run, first do:
+
+```bash
+鲤 (build)
+```
+
+And then:
+
+```
+鲤 (run)
+```
+
+## Running code from the terminal
+
+If you don't want to work in the REPL and use a more classic "compile & run" setup, do this:
+
+```bash
+$ carp some_file.carp -x
+```
+
+Any files you list as arguments to `carp` will be loaded (this works when starting the REPL too).
+The `-x` flag means that you want to compile and run the code immedately, exiting afterwards.
+
+If you just want to build the executable, use `-b` instead:
+
+```bash
+$ carp some_file.carp -b
+```
diff --git a/Manual.md b/Manual.md
index 6e8d237..3f99142 100644
--- a/Manual.md
+++ b/Manual.md
@@ -3,6 +3,7 @@
 ### Related pages
 
 * [Installation](Install.md) - how to acquire and configure the Carp compiler
+* [How To Run Code](HowToRunCode.md) - compile and execute .carp files
 * [Tooling](Tooling.md) - supported editors
 * [Libraries](Libraries.md) - how to work with libraries and modules
 * [Multimedia](Multimedia.md) - graphics, sounds, etc
@@ -12,7 +13,7 @@
 
 To learn more about the Carp language and its syntax and semantics, check out the [Carp Language Guide](LanguageGuide.md).
 
-### Basics
+### REPL Basics
 
 The Carp language is very tightly integrated with the REPL, everything you want to do to your program can be controlled from here.