wren/doc/site/getting-started.markdown

^title Getting Started

## Trying out the language

If you'd like to try Wren, you have a few options.

 *  **In your browser.** You can try Wren **[right here](./try/)**!
 *  **On your computer.** The [Wren CLI](cli) project is a downloadable executable
      to run scripts with access to file io and more. See the [Wren CLI docs](cli).
 * **Embedded in your code.** See how to [build and embed Wren](#embed-the-vm) below.   
    And then read the [embedding guide](embedding)!

Once you have somewhere to explore, it's time to [learn the
language](syntax.html).

---

## Embed the VM

**The Wren Virtual Machine** is the core of the language that executes Wren
    source code. It is just a library, not a standalone application. It's
    designed to be [embedded][] in a larger host application.

It has no dependencies beyond the C standard library.
You can use it as a static library, shared library, or simply compile the source into your app.

### Building Wren

To build the Wren library, we look inside the `projects/` folder.
In here you'll find ready to go projects for `Visual Studio`, `XCode` and tools like `make`.

 * **Windows** Open `wren.sln` inside `projects/vs2019/` (or `vs2017`), hit build.
 * **Mac** Open `wren.xcworkspace` inside `projects/xcode/`, hit build.
 * **Linux** Run `make` inside of `projects/make/`.

In each case, **there will be library files generated into the root `lib/` folder**.   
These are what you'll link into your project, based on your needs.

* **Static Linking** `wren.lib` on Windows, `libwren.a` elsewhere.
* **Dynamic Linking** `wren.dll` on Windows, `libwren.so` on Linux, and `libwren.dylib` on Mac.

<small>
  Note that the default build will also generate `wren_test` inside of `bin/`,   
  a binary that is used to run the language tests. It can execute simple scripts.
</small>

**Other platforms**   
If your platform isn't explicitly supported,
it is recommended that you include the Wren source
in your project for a portable experience.

### Including the code in your project

**all source files**   
The alternative to building via the provided projects is to include the wren source code in your project.
Since it has no dependencies this is simple, all the code in `src/` comes along. There's a readme in `src/` for details.

**'amalgamated' build**   
If you want an even simpler way, there's an 'amalgamated' build (often called `blob`, or `unity` builds.).
This is _all of the wren source code in one file_.

This file can be generated by running `python3 util/generate_amalgamation.py > build/wren.c`, 
which saves the generated output in `build/wren.c`.

Include `build/wren.c` and `src/include/wren.h` in your project code and you're good to go.
<small>Ideally later we can automate generating this and include it in the repo.</small>

---

[embedded]: embedding

If you run into bugs, or have ideas or questions, any of
the following work:

 *  Join the [discord community][discord].
 *  Ask on the [Wren mailing list][list] (which is pretty quiet).
 *  Tell us on twitter at [@munificentbob][twitter] or [@ruby0x1][twitter0x1].
 *  [File a ticket][issue] at [the GitHub repo][repo].
 *  The CLI also has [tickets][issue_cli] and a [GitHub repo][repo_cli] too.
 *  Pull requests are welcome.

[discord]: https://discord.gg/Kx6PxSX
[list]: https://groups.google.com/forum/#!forum/wren-lang
[twitter]: https://twitter.com/intent/user?screen_name=munificentbob
[twitter0x1]: https://twitter.com/intent/user?screen_name=ruby0x1
[issue]: https://github.com/wren-lang/wren/issues
[repo]: https://github.com/wren-lang/wren
[issue_cli]: https://github.com/wren-lang/wren-cli/issues
[repo_cli]: https://github.com/wren-lang/wren-cli