Fix mdbook build, add travis-ci, and publish book

gnzlbg · gnzlbg · commit af01162cb7fe · 2019-03-14T18:50:56.000+01:00
Closes #1 . Closes #27 .
diff --git a/.travis.yml b/.travis.yml
@@ -0,0 +1,14 @@
+language: rust
+sudo: false
+rust: nightly
+
+install: cargo install mdbook
+script: cd reference && mdbook build && mdbook test
+deploy:
+  provider: pages
+  skip-cleanup: true
+  github-token: $GITHUB_TOKEN
+  local-dir: reference/book
+  keep-history: false
+  on:
+    branch: master
diff --git a/README.md b/README.md
@@ -1,5 +1,7 @@
 # unsafe-code-guidelines
 
+[![Travis-CI Status]][travis]
+
 Home for the Unsafe Code Guidelines (UCG) effort. The goal of the Unsafe
 Code Guidelines effort is to collaboratively produce a "reference
 guide" for writing unsafe code that what kinds of things unsafe code
@@ -49,6 +51,18 @@ Guidelines Reference" here.][rr]
 
 [rr]: https://github.com/rust-rfcs/unsafe-code-guidelines/blob/master/reference/src/SUMMARY.md
 
+### Build instructions
+
+Make sure that `mdbook` is installed:
+
+> cargo install mdbook
+
+and execute `mdbook build` or `mdbook serve` in the `reference/` directory.
+
+### Link to the current version of the book
+
+[Here](https://rust-rfcs.github.io/unsafe-code-guidelines/book).
+
 ## Chat platform, discussion cadence
 
 Most of the discussion takes place here in GitHub issues. Many of us
@@ -77,3 +91,6 @@ effort to explain how to write Rust code, rather than a reference.
 [The nikomatsakis/rust-memory-model
 repository](https://github.com/nikomatsakis/rust-memory-model) was a
 previous effort and contains a lot of good links and info.
+
+[travis]: https://travis-ci.org/rust-rfcs/unsafe-code-guidelines
+[Travis-CI Status]: https://travis-ci.org/rust-rfcs/unsafe-code-guidelines.svg?branch=master
diff --git a/reference/src/SUMMARY.md b/reference/src/SUMMARY.md
@@ -1,18 +1,7 @@
 # Summary
 
-- [Introduction](./introduction.md)
-- [Areas of active discussion](./active_discussion.md)
-  - [Aliasing and memory model](./active_discussion/aliasing.md)
-  - [Cryptographic concerns](./active_discussion/crypto_concerns.md)
-    - [Keeping secrets](./active_discussion/crypto_concerns/keeping_secrets.md)
-    - [Constant time code](./active_discussion/crypto_concerns/constant_time_code.md)
-    - [Zeroing](./active_discussion/crypto_concerns/zeroing.md)
-  - [Data structure layout](./active_discussion/layout.md)
-  - [Stable addresses](./active_discussion/stable_addresses.md)
-  - [Storage liveness](./active_discussion/storage_liveness.md)
-  - [Uninhabited types like `!` and exhaustiveness](./active_discussion/uninhabited_types.md)
-  - [Unions](./active_discussion/unions.md)
-  - [Uninitialized memory](./active_discussion/uninitialized_memory.md)
+[Glossary](./glossary.md)
+
 - [Data layout](./layout.md)
   - [Structs and tuples](./layout/structs-and-tuples.md)
   - [Integers and Floating Points](./layout/integers-floatingpoint.md)
@@ -21,5 +10,4 @@
   - [Arrays and Slices](./layout/arrays-and-slices.md)
   - [Packed SIMD vectors](./layout/packed-simd-vectors.md)
 - [Optimizations](./optimizations.md)
-  - [Optimizing immutable memory](./optimizations/immutable_memory.md) 
-- [Glossary](./glossary.md)
+  - [Return value optimization](./optimizations/return_value_optimization.md)
diff --git a/reference/src/chapter_1.md b/reference/src/chapter_1.md
diff --git a/reference/src/glossary.md b/reference/src/glossary.md
@@ -25,7 +25,7 @@ Moreover, arguments passed to a function must be valid at the type given in the
 OPEN QUESTION: Are there more cases where data must be valid?
 
 In terms of code, some data computed by `TERM` is valid at type `T` if and only if the following program does not have UB:
-```rust
+```rust,ignore
 fn main() { unsafe {
   let t: T = std::mem::transmute(TERM);
 } }
@@ -37,7 +37,7 @@ The safety invariant can be temporarily violated by unsafe code, but must always
 It is not relevant when arguing whether some *program* has UB, but it is relevant when arguing whether some code safely encapsulates its unsafety -- IOW, it is relevant when arguing whether some *library* can be used by safe code to *cause* UB.
 
 In terms of code, some data computed by `TERM` (possibly constructed from some `arguments` that can be *assumed* to satisfy the safety invariant) is valid at type `T` if and only if the following library function can be safely exposed to arbitrary (safe) code as part of the public library interface:
-```rust
+```rust,ignore
 pub fn make_something(arguments: U) -> T { unsafe {
   std::mem::transmute(TERM)
 } }
diff --git a/reference/src/introduction.md b/reference/src/introduction.md
diff --git a/reference/src/layout.md b/reference/src/layout.md
@@ -0,0 +1 @@
+# Data layout
diff --git a/reference/src/layout/enums.md b/reference/src/layout/enums.md
@@ -181,19 +181,22 @@ enum TwoCases {
 This will be laid out equivalently to the following more 
 complex Rust types:
 
-```
+```rust
 #[repr(C)]
 union TwoCasesRepr {
     A: TwoCasesVariantA,
     B: TwoCasesVariantB,
 }
         
+# #[derive(Copy, Clone)]        
 #[repr(u8)]
 enum TwoCasesTag { A, B }
 
+# #[derive(Copy, Clone)]
 #[repr(C)]
 struct TwoCasesVariantA(TwoCasesTag, u8, u16);
 
+# #[derive(Copy, Clone)]
 #[repr(C)]
 struct TwoCasesVariantB(TwoCasesTag, u16);
 ```
@@ -222,7 +225,7 @@ occupy 6 bytes with `#[repr(C, u8)]`, as more padding is required.
 
 **Example.** The following enum:
 
-```rust
+```rust,ignore
 #[repr(C, Int)]
 enum MyEnum {
     A(u32),
@@ -234,7 +237,7 @@ enum MyEnum {
 
 is equivalent to the following Rust definition:
 
-```rust
+```rust,ignore
 #[repr(C)]
 struct MyEnumRepr {
     tag: MyEnumTag,
@@ -257,7 +260,6 @@ struct MyEnumPayloadB(f32, u64);
 
 #[repr(C)]
 struct MyEnumPayloadC { x: u32, y: u8 }
-}
 ```
 
 This enum can also be represented in C++ as follows:
@@ -308,7 +310,7 @@ type `T`.
 
 **Definition.** In some cases, the payload type may contain illegal
 values, which are called **niches**. For example, a value of type `&T`
-may never be NULL, and hence defines a niche consisting of the
+may never be `NULL`, and hence defines a niche consisting of the
 bitstring `0`.  Similarly, the standard library types [`NonZeroU8`]
 and friends may never be zero, and hence also define the value of `0`
 as a niche. (Types that define niche values will say so as part of the
@@ -367,13 +369,25 @@ As presently implemented, the compiler will use the same layout for
 structs and for single variant enums (as long as they do not have a
 `#[repr]` annotation that overrides that choice). So, for example, the
 struct `SomeStruct` and the enum `SomeEnum` would have an equivalent
-layout ([playground](https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&gist=3697ac684c3d021892694956df957653))::
+layout ([playground](https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&gist=3697ac684c3d021892694956df957653)):
 
 ```rust
 struct SomeStruct;
 enum SomeEnum {
   SomeVariant,
 }
+
+# fn main() {
+# use std::mem;
+let x = SomeStruct;
+let y = SomeEnum::SomeVariant;
+assert_eq!(
+    mem::size_of_val(&x), 
+    mem::size_of_val(&y),
+    "types have different sizes",
+);
+println!("types both have size {}", std::mem::size_of_val(&x));
+# }
 ```
 
 Similarly, the struct `SomeStruct` and the enum `SomeVariant` in this
@@ -385,6 +399,18 @@ struct SomeStruct { x: u32 }
 enum SomeEnum {
   SomeVariant { x: u32 },
 }
+
+# fn main() {
+# use std::mem;
+let x = SomeStruct { x: 22 };
+let y = SomeEnum::SomeVariant { x: 22 };
+assert_eq!(
+    mem::size_of_val(&x), 
+    mem::size_of_val(&y),
+    "types have different sizes",
+);
+println!("types both have size {}", mem::size_of_val(&x));
+}
 ```
 
 In fact, the compiler will use this optimized layout even for enums
@@ -393,10 +419,22 @@ is uninhabited
 ([playground](https://play.rust-lang.org/?version=stable&mode=debug&edition=2018&gist=3cc1484c5b91097f3dc2015b7c207a0e)):
 
 ```rust
+# enum Void { }
 struct SomeStruct { x: u32 }
 enum SomeEnum {
   SomeVariant { x: u32 },
   UninhabitedVariant { y: Void },
 }
-```    
 
+# fn main() {
+# use std::mem;
+let x = SomeStruct { x: 22 };
+let y = SomeEnum::SomeVariant { x: 22 };
+assert_eq!(
+    mem::size_of_val(&x), 
+    mem::size_of_val(&y),
+    "types have different sizes",
+);
+println!("types both have size {}", mem::size_of_val(&x));
+# }
+```
diff --git a/reference/src/layout/integers-floatingpoint.md b/reference/src/layout/integers-floatingpoint.md
@@ -1,9 +1,10 @@
 # Layout of Boolean, Floating Point, and Integral Types
 This chapter represents the consensus from issue [#9]. It documents the memory layout and considerations for `bool`, `usize`, `isize`, floating point types, and integral types.
+
 [#9]: https://github.com/rust-rfcs/unsafe-code-guidelines/issues/9
 
 ## Overview
-These are all scalar types, representing a single value. These types have no layout variants (no #[repr(C)] or #[repr(Rust)]. Their size is fixed and well-defined across FFI boundaries and map to their corresponding integral types in the C ABI.
+These are all scalar types, representing a single value. These types have no layout variants (no `#[repr(C)]` or `#[repr(Rust)]`). Their size is fixed and well-defined across FFI boundaries and map to their corresponding integral types in the C ABI.
 - `bool`: 1 byte
   - any `bool` can be cast into an integer, taking on the values 1 (true) or 0 (false)
 - `usize`, `isize`: pointer-sized unsigned/signed integer type
@@ -19,11 +20,11 @@ These are all scalar types, representing a single value. These types have no lay
   - not ABI compatible
   - represents [Unicode scalar value](http://www.unicode.org/glossary/#unicode_scalar_value)
 
-##`usize`/`isize`
+## `usize`/`isize`
 Types `usize` and `isize` are committed to having the same size as a native pointer on the platform. The layout of `usize` determines the following:
 - how much a pointer of a certain type can be offseted,
 - the maximum size of Rust objects (because size_of/size_of_val return `usize`),
-- the maximum number of elements in an array ([T; N: usize]),
+- the maximum number of elements in an array (`[T; N: usize]`),
 - `usize`/`isize` in C FFI are compatible with C's `uintptr_t` / `intptr_t` (and have the same size and alignment).
 
 The maximum size of any single value must fit within `usize` to [ensure that pointer diff is representable](https://github.com/rust-rfcs/unsafe-code-guidelines/pull/5#discussion_r212703192).
diff --git a/reference/src/layout/packed-simd-vectors.md b/reference/src/layout/packed-simd-vectors.md
@@ -25,7 +25,7 @@ Packed SIMD vector types are `repr(simd)` homogeneous tuple-structs containing
 `N` elements of type `T` where `N` is a power-of-two and the size and alignment
 requirements of `T` are equal:
 
-```rust
+```rust,ignore
 #[repr(simd)]
 struct Vector<T, N>(T_0, ..., T_(N - 1));
 ```
@@ -36,7 +36,7 @@ The size of `Vector` is `N * size_of::<T>()` and its alignment is an
 _implementation-defined_ function of `T` and `N` greater than or equal to
 `align_of::<T>()`. That is:
 
-```rust
+```rust,ignore
 assert_eq!(size_of::<Vector<T, N>>(), size_of::<T>() * N);
 assert!(align_of::<Vector<T, N>>() >= align_of::<T>());
 ```
@@ -47,7 +47,7 @@ same `N` have the same size and alignment.
 Vector elements are laid out in source field order, enabling random access to
 vector elements by reinterpreting the vector as an array:
 
-```rust
+```rust,ignore
 union U {
    vec: Vector<T, N>,
    arr: [T; N]
@@ -70,7 +70,7 @@ unsafe {
 * **Blocked**: Should the layout of packed SIMD vectors be the same as that of
   homogeneous tuples ? Such that:
 
-  ```rust
+  ```rust,ignore
   union U {
     vec: Vector<T, N>,
     tup: (T_0, ..., T_(N-1)),
diff --git a/reference/src/layout/structs-and-tuples.md b/reference/src/layout/structs-and-tuples.md
@@ -12,7 +12,7 @@ not to change until an RFC ratifies them.
 In general, an anonymous tuple type `(T1..Tn)` of arity N is laid out
 "as if" there were a corresponding tuple struct declared in libcore:
 
-```rust
+```rust,ignore
 #[repr(Rust)]
 struct TupleN<P1..Pn:?Sized>(P1..Pn);
 ```
@@ -50,7 +50,7 @@ Some related discussion:
 
 Structs come in two principle varieties:
 
-```rust
+```rust,ignore
 // Structs with named fields
 struct Foo { f1: T1, .., fn: Tn }
 
@@ -61,7 +61,7 @@ struct Foo(T1, .., Tn);
 In terms of their layout, tuple structs can be understood as
 equivalent to a named struct with fields named `0..n-1`:
 
-```rust
+```rust,ignore
 struct Foo {
   0: T1,
   ...
@@ -283,7 +283,7 @@ void some_function(uint32_t value) { .. }
 It is **incorrect** to pass in a struct as that value, even if that
 struct is `#[repr(C)`] and has only one field:
 
-```rust
+```rust,ignore
 #[repr(C)]
 struct Foo { x: u32 }
 
@@ -390,5 +390,3 @@ proposal (and -- further -- it does not match our existing behavior):
   thread](https://github.com/rust-rfcs/unsafe-code-guidelines/pull/31#discussion_r224955817)).
 - Many people would prefer the name ordering to be chosen for
   "readability" and not optimal layout.
-
-## Footnotes
diff --git a/reference/src/layout/unions.md b/reference/src/layout/unions.md
@@ -9,7 +9,7 @@ not to change until an RFC ratifies them.
 The only degree of freedom the compiler has when computing the layout of a union
 like
 
-```rust
+```rust,ignore
 union U { f1: T1, f2: T2 }
 ```
 
diff --git a/reference/src/optimizations/immutable_memory.md b/reference/src/optimizations/immutable_memory.md
diff --git a/reference/src/optimizations/return_value_optimization.md b/reference/src/optimizations/return_value_optimization.md
@@ -1,6 +1,6 @@
 We should turn
 
-```rust
+```rust,ignore
 // y unused
 let mut x = f();
 g(&mut x);
@@ -10,7 +10,7 @@ y = x;
 
 into
 
-```rust
+```rust,ignore
 y = f();
 g(&mut y);
 ```
diff --git a/reference/src/representation.md b/reference/src/representation.md
