Skip to content

Commit bf6bf93

Browse files
jsoversonjsoverson
committed
added book asciidoc
1 parent 975c4e9 commit bf6bf93

File tree

3,582 files changed

+575043
-3
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

3,582 files changed

+575043
-3
lines changed

‎.gitignore

+3
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,6 @@
11
target
22
**/*/.DS_Store
33
**/*/node_modules
4+
vendor
5+
.bundle
6+
Gemfile.lock

‎Gemfile

+5
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
source "https://rubygems.org"
2+
3+
gem "asciidoctor"
4+
gem "asciidoctor-pdf"
5+
gem "rouge"

‎LICENSE

+394
Large diffs are not rendered by default.

‎LICENSE-CODE

+395
Large diffs are not rendered by default.

‎Makefile

+15
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
# Enforce bash as the shell for consistency
2+
SHELL := bash
3+
# Use bash strict mode
4+
.SHELLFLAGS := -eu -o pipefail -c
5+
MAKEFLAGS += --warn-undefined-variables
6+
MAKEFLAGS += --no-builtin-rules
7+
8+
.PHONY: book
9+
book:
10+
bundle exec asciidoctor-pdf -a source-highlighter=rouge book/book.adoc --o from-javascript-to-rust.pdf
11+
12+
.PHONY: deps
13+
deps:
14+
bundle install
15+

‎README.md

+26-3
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,26 @@
1-
# Advent of Rust: 24 Days From node.js to Rust
1+
# From JavaScript to Rust ebook
22

3-
This repository is for code related to the guide at: https://vino.dev/blog/node-to-rust-day-1-rustup/
3+
This repository houses an ebook-ified version of the 24+ post series started on [vino.dev](https://vino.dev/blog/node-to-rust-day-1-rustup/).
44

5-
## Running projects
5+
## How to build
6+
7+
The ebook is built using [asciidoctor](https://docs.asciidoctor.org/) and requires ruby >2.3.
8+
9+
Install the ruby dependencies via `make deps`
10+
11+
```console
12+
$ make deps
13+
```
14+
15+
Build a PDF via the command `make book`
16+
17+
```console
18+
$ make book
19+
```
20+
21+
## Running code and projects
22+
23+
All code are housed in the `src/` directory.
624

725
### Day 4
826

@@ -189,3 +207,8 @@ First you must cd into `crates/day-22/wapc-guest`
189207
- `cargo run -p day-23-rc-arc --bin arc`
190208
- `cargo run -p day-23-rc-arc --bin rwlock`
191209
- `cargo run -p day-23-rc-arc --bin async` - intentionally does not compile
210+
211+
## License
212+
213+
Book: Creative Commons BY-NC-ND 4.0
214+
Code: Creative Commons BY 4.0

‎book/.bundle/config

+2
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
---
2+
BUNDLE_PATH: "vendor/bundle"

‎book/README.md

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# From JavaScript to Rust ebook
2+
3+
This repository houses an ebook-ified version of the 24+ post series started on [vino.dev](https://vino.dev/blog/node-to-rust-day-1-rustup/).
4+
5+
## How to build
6+
7+
The ebook is built using [asciidoctor](https://docs.asciidoctor.org/) and requires ruby >2.3.
8+
9+
Install the ruby dependencies via `make deps`
10+
11+
```console
12+
$ make deps
13+
```
14+
15+
Build a PDF via the command `make book`
16+
17+
```console
18+
$ make book
19+
```
20+
21+
## License
22+
23+
Creative Commons BY-NC-ND 4.0

‎book/book.adoc

+41
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
:author: Jarrod Overson
2+
:email: [email protected]
3+
:revnumber: v0.1
4+
:revdate: 02.22.2022
5+
:notitle:
6+
:doctype: book
7+
:chapter-label:
8+
:toc: left
9+
:toclevels: 2
10+
:sectnums: |,all|
11+
:toc-title: Table of Contents
12+
:front-cover-image: image::images/cover.png[leveloffset=0]
13+
:description: Learn Rust by mapping what you already know from JavaScript and node.js to their counterparts in the Rust ecosystem
14+
15+
= Go From JavaScript to Rust
16+
17+
include::./chapters/chapter-0-introduction.adoc[leveloffset=1]
18+
include::./chapters/chapter-1-rustup.adoc[leveloffset=1]
19+
include::./chapters/chapter-2-cargo.adoc[leveloffset=1]
20+
include::./chapters/chapter-3-vscode.adoc[leveloffset=1]
21+
include::./chapters/chapter-4-hello-world.adoc[leveloffset=1]
22+
include::./chapters/chapter-5-ownership.adoc[leveloffset=1]
23+
include::./chapters/chapter-6-strings-part1.adoc[leveloffset=1]
24+
include::./chapters/chapter-7-syntax-and-language.adoc[leveloffset=1]
25+
include::./chapters/chapter-8-types-hashmaps-and-structs.adoc[leveloffset=1]
26+
include::./chapters/chapter-9-structs-and-behavior.adoc[leveloffset=1]
27+
include::./chapters/chapter-10-traits.adoc[leveloffset=1]
28+
include::./chapters/chapter-11-module-system.adoc[leveloffset=1]
29+
include::./chapters/chapter-12-strings-part2.adoc[leveloffset=1]
30+
include::./chapters/chapter-13-result-and-option.adoc[leveloffset=1]
31+
include::./chapters/chapter-14-managing-errors.adoc[leveloffset=1]
32+
include::./chapters/chapter-15-closures.adoc[leveloffset=1]
33+
include::./chapters/chapter-16-lifetimes-and-references.adoc[leveloffset=1]
34+
include::./chapters/chapter-17-arrays-loops-and-iterators.adoc[leveloffset=1]
35+
include::./chapters/chapter-18-async.adoc[leveloffset=1]
36+
include::./chapters/chapter-19-starting-a-project.adoc[leveloffset=1]
37+
include::./chapters/chapter-20-cli-args-and-logging.adoc[leveloffset=1]
38+
include::./chapters/chapter-21-building-and-running-webassembly.adoc[leveloffset=1]
39+
include::./chapters/chapter-22-using-json.adoc[leveloffset=1]
40+
include::./chapters/chapter-23-arc-rc-mutex-and-rwlock.adoc[leveloffset=1]
41+
include::./chapters/chapter-24-crates-and-tools.adoc[leveloffset=1]

‎book/chapters/chapter-0-introduction.adoc

+23
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
= Introduction
2+
3+
== A guide to Rust from a node.js developer's perspective.
4+
5+
Welcome to the wonderful world of Rust! Each chapter will take concepts you know in JavaScript and node.js and translate them to their Rust counterparts. The first chapters start with the basics, like getting set up with Rust via a tool similar to `nvm` (`rustup`), using the package manager (`cargo`), and setting up VS Code. Later chapters go over language gotchas, how to perform common JavaScript tasks in Rust, and we'll finish up by touching on solid dependencies to start adding to your projectss.
6+
7+
== Wait, why does anyone need to learn anything but JavaScript?
8+
9+
I _love_ JavaScript. I've been coding JavaScript it since I first saw it in Netscape. I've written more lines of JavaScript than any other language. I'm a fan, but I know where the language falls short. It's fast, but not that fast. It's easy to write, but easy to screw up. Large projects become unwieldy fast. TypeScript helps scale JavaScript but it adds its own complexity and still doesn't make anything faster. Server-side JavaScript relies on node.js which is common but not ubiquitous. If you want to distribute something self-contained, there aren't great answers.
10+
11+
When you start stretching passed what JavaScript is best at, it's helpful to have another language to turn to.
12+
13+
== Why Rust?
14+
15+
You could use C, C{pp}, C#, Go, Java, Kotlin, Haskell or a hundred others. Rust is notoriously difficult even for system programmers to get into. Why bother with Rust? Think about your languages as tools in your toolbox. When you fill your toolbox, you don't want 10 tools that solve similar problems. You want tools that complement each other and give you the ability to fix everything an anything. You already have JavaScript, a developer super-tool. It's a high level language that's good enough to run just about everything everywhere. If you're picking up a new language, you might as well go to the extreme and pick a no-compromise, low-level powerhouse.
16+
17+
Also, WebAssembly.
18+
19+
Rust's tooling and support for WebAssembly is better than everything else out there. You can rewrite CPU-heavy JavaScript logic into Rust and run it as WebAssembly. Which basically makes you a superhero. With JavaScript and Rust, there's nothing you can't handle.
20+
21+
== How to use this book
22+
23+
This book is not a deep, comprehensive Rust tutorial. It's meant to bootstrap experienced programmers into Rust. We'll take common node.js workflows and idiomatic JavaScript and TypeScript and map them to their Rust counterparts. This book balances technical accuracy with readability. It errs on the side of "gets the point across" vs being 100% correct. When something is glossed over, we'll add links for those looking to dive deeper.

‎book/chapters/chapter-1-rustup.adoc

+93
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
= Installing rust with `rustup`
2+
3+
https://github.com/nvm-sh/nvm[nvm] (or https://github.com/coreybutler/nvm-windows[nvm-windows]) are indispensible tools. They manage seamlessly installing and switching between versions of node.js on the same system.
4+
5+
The equivalent in Rust's world is https://rustup.rs/[rustup].
6+
7+
Rustup manages your Rust installation as well as additonal targets (like WebAssembly) and core tools like `cargo` (Rust's `npm`), `clippy` (Rust's `eslint`), `rustfmt` (Rust's `prettier`).
8+
9+
After installing `rustup`, run it without any subcommands and explore what it has to offer.
10+
11+
[source,text]
12+
----
13+
$ rustup
14+
rustup 1.24.3 (ce5817a94 2021-05-31)
15+
The Rust toolchain installer
16+
17+
USAGE:
18+
rustup [FLAGS] [+toolchain] <SUBCOMMAND>
19+
20+
FLAGS:
21+
-v, --verbose Enable verbose output
22+
-q, --quiet Disable progress output
23+
-h, --help Prints help information
24+
-V, --version Prints version information
25+
26+
ARGS:
27+
<+toolchain> release channel (e.g. +stable) or custom toolchain to set override
28+
29+
SUBCOMMANDS:
30+
show Show the active and installed toolchains or profiles
31+
update Update Rust toolchains and rustup
32+
check Check for updates to Rust toolchains and rustup
33+
default Set the default toolchain
34+
toolchain Modify or query the installed toolchains
35+
target Modify a toolchain's supported targets
36+
component Modify a toolchain's installed components
37+
override Modify directory toolchain overrides
38+
run Run a command with an environment configured for a given toolchain
39+
which Display which binary will be run for a given command
40+
doc Open the documentation for the current toolchain
41+
man View the man page for a given command
42+
self Modify the rustup installation
43+
set Alter rustup settings
44+
completions Generate tab-completion scripts for your shell
45+
help Prints this message or the help of the given subcommand(s)
46+
47+
DISCUSSION:
48+
Rustup installs The Rust Programming Language from the official
49+
release channels, enabling you to easily switch between stable,
50+
beta, and nightly compilers and keep them updated. It makes
51+
cross-compiling simpler with binary builds of the standard library
52+
for common platforms.
53+
54+
If you are new to Rust consider running `rustup doc --book` to
55+
learn Rust.
56+
----
57+
58+
`rustup show` will show you what is currently installed.
59+
60+
`rustup completions` will help you enable CLI autocompletion for tools like `rustup` and `cargo`.
61+
62+
`rustup component` lets you add additonal components.
63+
64+
`rustup update` will update you to the latest version.
65+
66+
`rustup install stable|nightly|1.57` will install a specific version or the latest stable/nightly versions.
67+
68+
By default, rustup will install the latest version of `rust` and `cargo` and you should be ready to go right away. Give it a shot with.
69+
70+
[source,sh]
71+
----
72+
$ rustc --version
73+
rustc 1.57.0 (59eed8a2a 2021-11-01)
74+
75+
$ cargo --version
76+
cargo 1.56.0 (4ed5d137b 2021-10-04)
77+
----
78+
79+
If it doesn't work, you may need to restart your shell to update your PATH.
80+
81+
== `rust-toolchain.toml`
82+
83+
Specifying your toolchain with rustup is easy enough. As you get deeper, you may get into configurations where different projects require different toolchains or Rust versions. That's where `rust-toolchain.toml` comes into play. Specify your project's required toolchain, targets, and supporting tools here so that `cargo` and `rustup` can work automagically, e.g.
84+
85+
`toml {title = "rust-toolchain.toml"}
86+
[toolchain]
87+
channel = "1.56.0"
88+
components = [ "rustfmt", "clippy" ]
89+
`
90+
91+
== Next steps
92+
93+
Next up we'll take a look at `cargo`, Rust's `npm` and the additional tools that will help reach parity with common workflows: link:./chapter-2-cargo.adoc[Chapter 2: From npm to cargo].

0 commit comments

Comments
 (0)