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.

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

feat(docs): add features from v0.26 #769

Merged
merged 3 commits into from
Nov 17, 2024
Merged
Changes from 1 commit
Commits
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
Prev Previous commit
Next Next commit
feat(tutorial): add welcome section
emil14 committed Nov 17, 2024
commit 18da545437bfa02b7805aea99cb15b5d63d8bae4
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -4,7 +4,7 @@

<h1>Dataflow Programming Language</h1>

[Documentation](./docs/)
[Documentation](./docs/README.md)
| [Examples](./examples/)
| [Community](#-community)
| [Releases](https://github.com/nevalang/neva/releases)
28 changes: 13 additions & 15 deletions docs/README.md
Original file line number Diff line number Diff line change
@@ -1,21 +1,19 @@
# Documentation

This document provides an overview of Nevalang, its core concepts, and how to use it effectively.
Welcome to Nevalang documentation!

## About this Document
## [Tutorial](./tutorial.md)

1. Covers conceptual features, some not yet implemented
2. Compiles initial language information
3. Focuses on fundamental aspects rather than specific APIs
Best place to start.

## Table of Contents
## [Style Guide](./style_guide.md)

- [About](./about.md)
- [Program Structure](./program_structure.md)
- [Types](./types.md)
- [Constants](./constants.md)
- [Interfaces](./interfaces.md)
- [Components](./components.md)
- [Networks](./networks.md)
- [Style Guide](./style_guide.md)
- [Questions and Answers](./qa.md)
Best practices to follow.

## [The Book](./book/README.md)

A deep dive into the language and how it works. Make sure you've read tutorial!

## [Questions and Answers](./qna.md)

If you curious why things exactly the way they are.
18 changes: 18 additions & 0 deletions docs/book/README.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
# The Book

Welcome to "The Book" - an in-depth resource on Nevalang. This extension to the tutorial and style guide provides a deeper understanding of the language's inner workings. While the tutorial helps you start programming in Nevalang, this book explores advanced concepts and features. It is recommended for those seeking a thorough understanding of the language, but can be read at your own pace.

This book is designed to be read sequentially, as each chapter builds upon concepts introduced in previous ones. However, you can also use it as a reference by jumping to specific topics of interest.

> If you just want to get your feet wet, read the [tutorial](../tutorial.md) instead.

## Table of Contents

- [About](./about.md) - Introduction to Nevalang's key characteristics and motivations
- [Program Structure](./program_structure.md) - Understanding how Nevalang programs are organized
- [Types](./types.md) - Deep dive into Nevalang's type system
- [Constants](./constants.md) - Working with compile-time known values
- [Interfaces](./interfaces.md) - Component signatures and dependency injection
- [Components](./components.md) - Core computational units in Nevalang
- [Networks](./networks.md) - Understanding message passing and connections
- [Style Guide](./style_guide.md) - Best practices for writing clean Nevalang code
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
126 changes: 126 additions & 0 deletions docs/tutorial.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,126 @@
# Tutorial

Welcome to a tour of the Nevalang programming language. This tutorial will introduce you to Nevalang through a series of guided examples.

1. [Welcome](#welcome)
- [What kind of language is this?](#what-kind-of-language-is-this)
- [Installation](#installation)
- [Hello, World!](#hello-world)
- [Compiling programs](#compiling-programs)

<!-- Advanced topics: tracing -->

## Welcome

### What Kind of Language is This?

Nevalang is a general-purpose programming language that uses dataflow instead of control flow, lacking variables and functions, and expressing programs through pure message passing with nodes, connections, and ports. It is implicitly parallel, meaning all nodes operate in parallel by default, eliminating the need for threads, coroutines, or async-await, which simplifies some tasks while complicating others.

Influenced by functional programming, Nevalang embraces immutability and higher-order components, disallowing data mutation and shared state. It is a compiled, strongly statically-typed, garbage-collected language, sharing Go's abstraction level but aligning more with Rust's strictness. Using Go as a backend, it supports all Go targets, including WASM and cross-compiled machine code.

### Installation

#### Requirements

Make sure you have [Go compiler](https://go.dev/dl/) installed.

#### Via Shell Script

For Mac OS and Linux:

```bash
curl -sSL https://raw.githubusercontent.com/nevalang/neva/main/scripts/install.sh | bash
```

If your device is connected to a chinese network:

```bash
curl -sSL https://raw.githubusercontent.com/nevalang/neva/main/scripts/cnina/install.sh | bash
```

For Windows (see [issue](https://github.com/nevalang/neva/issues/499) with Windows Defender, try manual download from [releases](https://github.com/nevalang/neva/releases) if installation won't work):

```batch
curl -o installer.bat -sSL https://raw.githubusercontent.com/nevalang/neva/main/scripts/install.bat && installer.bat
```

#### From Source

Here's how you can build Nevalang for all supported platforms

```
git clone github.com/nevalang/neva
cd neva
make build
```

After building is finished, pick the one for your architecture and put it in your `PATH`. The rest of the binaries can be removed.

If you don't have Make or you only want to build for your platform, open the `Makefile` in the root of the repository and check what the `build` command does. For example, to build for Mac OS, the instruction is `GOOS=darwin GOARCH=amd64 go build -ldflags="-s -w" -o neva-darwin-amd64 ./cmd/neva`

#### Testing

After installation is finished, you should be able to run the `neva` CLI from your terminal

```shell
neva version
```

It should emit something like `0.26.0`

### Hello, World!

Once you've installed the neva-cli, you are able to use the `new` command to scaffold new Nevalang projects

```bash
neva new my_awesome_project
```

Each new project contains a Hello World program, so we can just run it

```bash
neva run my_awesome_project/src
```

You should see the following output:

```bash
Hello, World!
```

If you open `my_awesome_project/src/main.neva` with your favorite IDE, you'll see this:

```neva
import { fmt }

def Main(start any) (stop any) {
println fmt.Println
---
:start -> { 'Hello, World!' -> println -> :stop }
}
```

Congratulations, you have just compiled and executed your first Nevalang program!

### Compiling Programs

As mentioned, `neva run` builds and runs the executable, then cleans up by removing the temporary binary. This is useful for development, but for production, we usually prefer separate compilation and execution. You can achieve this with the `neva build` command.

```neva
neva build my_awesome_project/src
```

This will produce an `output` file in the directory where neva-cli was executed, typically the project's root.

Run `neva build --help` to see various options. Here are some examples:

```shell
# will name output file "my_awesome_binary"
neva build my_awesome_project/src --output=my_awesome_binary

# will generate go code instead of machine code
neva build my_awesome_project/src --target=go

# will output my_awesome_wasm.wasm
neva build my_awesome_project/src --target=wasm --output=my_awesome_wasm
```