[rustc.git] / src / doc / nomicon / README.md

# The Rustonomicon

The Dark Arts of Advanced and Unsafe Rust Programming

Nicknamed "the Nomicon."

## NOTE: This is a draft document, and may contain serious errors

> Instead of the programs I had hoped for, there came only a shuddering
blackness and ineffable loneliness; and I saw at last a fearful truth which no
one had ever dared to breathe before — the unwhisperable secret of secrets — The
fact that this language of stone and stridor is not a sentient perpetuation of
Rust as London is of Old London and Paris of Old Paris, but that it is in fact
quite unsafe, its sprawling body imperfectly embalmed and infested with queer
animate things which have nothing to do with it as it was in compilation.

This book digs into all the awful details that are necessary to understand in
order to write correct Unsafe Rust programs. Due to the nature of this problem,
it may lead to unleashing untold horrors that shatter your psyche into a billion
infinitesimal fragments of despair.

## Requirements

Building the Nomicon requires [mdBook]. To get it:

[mdBook]: https://github.com/rust-lang/mdBook

```bash
cargo install mdbook
```

### `mdbook` usage

To build the Nomicon use the `build` sub-command:

```bash
mdbook build
```

The output will be placed in the `book` subdirectory. To check it out, open the
`index.html` file in your web browser. You can pass the `--open` flag to `mdbook
build` and it'll open the index page in your default browser (if the process is
successful) just like with `cargo doc --open`:

```bash
mdbook build --open
```

There is also a `test` sub-command to test all code samples contained in the book:

```bash
mdbook test
```

### `linkcheck`

We use the `linkcheck` tool to find broken links.
To run it locally:

```sh
curl -sSLo linkcheck.sh https://raw.githubusercontent.com/rust-lang/rust/master/src/tools/linkchecker/linkcheck.sh
sh linkcheck.sh --all nomicon
```

## Contributing

Given that the Nomicon is still in a draft state, we'd love your help! Please
feel free to open issues about anything, and send in PRs for things you'd like
to fix or change. If your change is large, please open an issue first, so we can
make sure that it's something we'd accept before you go through the work of
getting a PR together.
Commit	Line	Data
cc61c64b XL	1	# The Rustonomicon
	2
	3	The Dark Arts of Advanced and Unsafe Rust Programming
	4
	5	Nicknamed "the Nomicon."
	6
	7	## NOTE: This is a draft document, and may contain serious errors
	8
416331ca XL	9	> Instead of the programs I had hoped for, there came only a shuddering
	10	blackness and ineffable loneliness; and I saw at last a fearful truth which no
	11	one had ever dared to breathe before — the unwhisperable secret of secrets — The
	12	fact that this language of stone and stridor is not a sentient perpetuation of
	13	Rust as London is of Old London and Paris of Old Paris, but that it is in fact
cc61c64b XL	14	quite unsafe, its sprawling body imperfectly embalmed and infested with queer
	15	animate things which have nothing to do with it as it was in compilation.
	16
	17	This book digs into all the awful details that are necessary to understand in
	18	order to write correct Unsafe Rust programs. Due to the nature of this problem,
	19	it may lead to unleashing untold horrors that shatter your psyche into a billion
	20	infinitesimal fragments of despair.
	21
136023e0	22	## Requirements
cc61c64b XL	23
	24	Building the Nomicon requires [mdBook]. To get it:
	25
60c5eb7d	26	[mdBook]: https://github.com/rust-lang/mdBook
cc61c64b XL	27
cc61c64b XL	28	```bash
136023e0	29	cargo install mdbook
cc61c64b XL	30	```
cc61c64b XL	31
416331ca	32	### `mdbook` usage
cc61c64b	33
416331ca	34	To build the Nomicon use the `build` sub-command:
cc61c64b XL	35
cc61c64b XL	36	```bash
136023e0	37	mdbook build
cc61c64b XL	38	```
cc61c64b XL	39
416331ca XL	40	The output will be placed in the `book` subdirectory. To check it out, open the
	41	`index.html` file in your web browser. You can pass the `--open` flag to `mdbook
	42	build` and it'll open the index page in your default browser (if the process is
	43	successful) just like with `cargo doc --open`:
cc61c64b	44
cc61c64b	45	```bash
136023e0	46	mdbook build --open
cc61c64b XL	47	```
cc61c64b XL	48
416331ca	49	There is also a `test` sub-command to test all code samples contained in the book:
cc61c64b XL	50
cc61c64b XL	51	```bash
136023e0 XL	52	mdbook test
	53	```
	54
	55	### `linkcheck`
	56
	57	We use the `linkcheck` tool to find broken links.
	58	To run it locally:
	59
	60	```sh
	61	curl -sSLo linkcheck.sh https://raw.githubusercontent.com/rust-lang/rust/master/src/tools/linkchecker/linkcheck.sh
	62	sh linkcheck.sh --all nomicon
cc61c64b XL	63	```
	64
	65	## Contributing
	66
416331ca XL	67	Given that the Nomicon is still in a draft state, we'd love your help! Please
	68	feel free to open issues about anything, and send in PRs for things you'd like
	69	to fix or change. If your change is large, please open an issue first, so we can
	70	make sure that it's something we'd accept before you go through the work of
	71	getting a PR together.