merge: project-wide build fixes and tweaks

pull request #167 from ut-utp/imp/build-fixes
ut-utp · Jul 13, 2022 · 5e0f0eb · 5e0f0eb
2 parents af5e63e + d46b1da
commit 5e0f0eb
Show file tree

Hide file tree

Showing 87 changed files with 740 additions and 2,761 deletions.
diff --git a/.cargo/config b/.cargo/config
@@ -3,14 +3,181 @@
 # Ordinarily we would just set this but: we don't want to break regular
 # `cargo doc` for developers that don't have a nightly toolchain installed.
 # rustdocflags = ["--cfg", "docs"]
+#
+# Instead, we provide the `docs` alias.
+#
+# Similar to regular lints and clippy lints (below), we want to have one place
+# to stick our rustdoc lints.
+#
+# Sticking these in `rustdocflags` has two downsides:
+#   - these lints will not show up in your editor!
+#   - these lints block building docs!
+#
+# Unfortunately, I don't currently know of a better way.
+#
+# As a stopgap, we _do_ pass rustdoc `--cap-lints allow` in the `cargo docs`
+# alias below but that requires nightly Rust.
+rustdocflags = [
+    ### [rustdoc] https://doc.rust-lang.org/rustdoc/lints.html
+    "--deny", "rustdoc::broken_intra_doc_links",
+    "--deny", "missing-docs",
+    "--deny", "rustdoc::missing_crate_level_docs",
+    "--deny", "rustdoc::bare_urls",
+
+    # NOTE: `cargo` still sets `--cap-lints` when building docs for deps so
+    # these lints don't trigger there/break the docs build.
+]
+
+# TODO: in CI, set RUSTDOCFLAGS to `--cap-lints forbid`.
+# TODO: in CI, run rustdoc with "--show-coverage"
 
 [alias]
 # Requires `nightly` Rust!
 docs = [
-    "-Z", "unstable-options", '--config=build.rustdocflags=["--cfg", "docs"]',
-    "doc", "--all", "--document-private-items", "--all-features"
+    "-Z", "unstable-options",
+    "-Z", "rustdoc-scrape-examples=examples",
+    '--config=build.rustdocflags=["--cfg", "docs", "-Zunstable-options", "--show-type-layout", "--cap-lints=allow"]', # `--scrape-examples`, '--check-cfg', '--generate-link-to-definition'
+    "doc", "--workspace", "--document-private-items", "--all-features", # "--bins", "--examples",
 ]
 # Stable equivalent of the above.
 docs-stable = [
-    "doc", "--all", "--document-private-items"
+    "doc", "--workspace", "--document-private-items", "--all-features", # "--bins", "--examples"
+]
+
+build-all = ["build", "--workspace", "--all-features", "--all-targets"]
+check-all = ["check", "--workspace", "--all-features", "--all-targets"]
+fmt-all = ["fmt", "--workspace"]
+test-all = ["test", "--workspace", "--all-features", "--all-targets", "--no-fail-fast"]
+
+# We put this list here instead of in `lib.rs`/`main.rs`/CI workflows for a
+# couple of reasons:
+#   1) We'd like to not have to duplicate/update this list in every crate in
+#      this workspace
+#   2) For local development, we want running these lints to be _opt in_.
+#      Having, for example, missing documentation prevent you from compiling
+#      and testing while you're still figuring out how to implement something
+#      is counterproductive.
+#
+#      These lints *are* enforced by CI however we don't want to put this list
+#      in the CI workflow definition either because: we still want to have an
+#      easy way for developers to run exactly the checks CI will run, locally.
+#
+# The downside to this approach, as detailed in `.vscode/core.code-workspace`,
+# is that this alias does not play well with rust analyzer so there isn't an
+# easy way for developers to see these errors in their editor.
+#
+# In the future we may want to switch to:
+#   - clippy.toml, when it is implemented
+#     + https://github.com/rust-lang/rust-clippy/issues/1313
+#     + https://github.com/rust-lang/cargo/issues/5034
+#   - `cargo-cranky`, if we decide we're okay requiring developers to install it
+#     + https://github.com/ericseppanen/cargo-cranky
+#     + this supports rustc lints and also plays well with `rust-analyzer`
+clippy-all = ["clippy", "--all", "--all-features", "--all-targets", "--",
+    ### [rustc] allow by default lints: https://doc.rust-lang.org/rustc/lints/listing/allowed-by-default.html
+    # "--warn", "fuzzy_provenance_casts", # nightly
+    "--deny", "keyword_idents",
+    # "--warn", "lossy_provenance_casts", # nightly
+    "--deny", "missing_abi",
+    "--deny", "missing_debug_implementations",
+    "--deny", "missing_docs",
+    # "--deny", "must_not_suspend", # nightly
+    # "--warn", "non_exhaustive_omitted_patterns", # TODO: might be too noisy # nightly
+    "--deny", "noop_method_call",
+    "--deny", "unreachable_pub",
+    "--deny", "unsafe_op_in_unsafe_fn", # We want separate "SAFETY" comments!
+    "--warn", "unused_crate_dependencies", # TODO: might be too noisy
+    "--warn", "unused_extern_crates",
+    "--deny", "unused_import_braces",
+    "--deny", "unused_lifetimes",
+    "--deny", "unused_macro_rules",
+    "--deny", "unused_qualifications",
+    "--deny", "unused_results",
+    "--deny", "variant_size_differences",
+
+    ### [rustc] warn by default lints: https://doc.rust-lang.org/rustc/lints/listing/warn-by-default.html
+    "--deny", "warnings", # TODO: maybe don't do this..
+    "--deny", "asm_sub_register",
+    "--deny", "bad_asm_style",
+    "--deny", "bindings_with_variant_name",
+    "--deny", "clashing_extern_declarations",
+    "--deny", "coherence_leak_check",
+    "--deny", "const_evaluatable_unchecked",
+    "--deny", "const_item_mutation",
+    "--deny", "dead_code",
+    "--deny", "deprecated",
+    "--deny", "deprecated_cfg_attr_crate_type_name",
+    "--deny", "deprecated_where_clause_location",
+    "--deny", "deref_into_dyn_supertrait",
+    "--deny", "deref_nullptr",
+    "--deny", "duplicate_macro_attributes",
+    "--deny", "exported_private_dependencies",
+    "--deny", "forbidden_lint_groups",
+    "--deny", "improper_ctypes",
+    "--deny", "improper_ctypes_definitions",
+    "--deny", "invalid_doc_attributes",
+    "--deny", "invalid_value",
+    "--deny", "irrefutable_let_patterns",
+    "--deny", "large_assignments",
+    "--deny", "legacy_derive_helpers",
+    "--deny", "no_mangle_generic_items",
+    "--deny", "non_camel_case_types",
+    "--deny", "non_shorthand_field_patterns",
+    "--deny", "non_snake_case",
+    "--deny", "non_upper_case_globals",
+    "--deny", "overlapping_range_endpoints",
+    "--deny", "path_statements",
+    "--deny", "private_in_public",
+    "--deny", "redundant_semicolons",
+    "--deny", "renamed_and_removed_lints",
+    "--deny", "semicolon_in_expressions_from_macros",
+    "--deny", "suspicious_auto_trait_impls",
+    "--allow", "type_alias_bounds",
+    "--deny", "unconditional_recursion",
+    # "--deny", "undefined_naked_function_abi", # nightly
+    "--deny", "unexpected_cfgs",
+    "--deny", "unknown_lints",
+    "--deny", "unnameable_test_items",
+    "--deny", "unreachable_code",
+    "--deny", "unreachable_patterns",
+    "--deny", "unstable_name_collisions",
+    "--deny", "unsupported_calling_conventions",
+    "--deny", "unused_allocation",
+    "--deny", "unused_assignments",
+    "--deny", "unused_attributes",
+    "--deny", "unused_braces",
+    "--deny", "unused_comparisons",
+    "--deny", "unused_doc_comments",
+    "--deny", "unused_features",
+    "--deny", "unused_imports",
+    "--deny", "unused_macros",
+    "--deny", "unused_must_use",
+    "--deny", "unused_mut",
+    "--deny", "unused_parens",
+    "--deny", "unused_variables",
+    "--deny", "where_clauses_object_safety",
+    "--deny", "while_true",
+
+    ### [rustc] deny by default lints: https://doc.rust-lang.org/rustc/lints/listing/deny-by-default.html
+    "--forbid", "macro_expanded_macro_exports_accessed_by_absolute_paths",
+    "--forbid", "unknown_crate_types",
+
+    ####### Clippy Lints: https://rust-lang.github.io/rust-clippy/master/ #######
+
+    ### [clippy] cargo
+    "--deny", "clippy::cargo_common_metadata",
+    "--warn", "clippy::multiple_crate_versions",
+    "--deny", "clippy::negative_feature_names",
+    "--deny", "clippy::redundant_feature_names",
+    "--deny", "clippy::wildcard_dependencies",
+
+    # TODO: peruse the other clippy lints (the defaults are pretty good though)
 ]
+lint = ["clippy-all"]
+
+b = "build-all"
+c = "check-all"
+d = "docs-stable"
+f = "fmt-all"
+t = "test-all"
+l = "lint"
diff --git a/.vscode/core.code-workspace b/.vscode/core.code-workspace
@@ -0,0 +1,82 @@
+{
+	"folders": [
+		{ "path": ".." }
+	],
+	"settings": {
+		"files.exclude": {
+			"target": true
+		},
+
+		"rust-analyzer": {
+			"cargo.features": "all",
+			"checkOnSave": {
+				"allTargets": true,
+				"features": "all",
+
+				// Note: we cannot actually use `lint` here because it cannot
+				// accept `cargo clippy` args `--workspace` and `--all-features`
+				// (because it uses `--` and passes the underlying clippy
+				// invocation args).
+				//
+				// This means developers must run the `lint` build task to see
+				// the errors CI will complain about *and* that there isn't an
+				// easy way for developers to see these errors in their editor.
+				"command": "clippy",
+			}
+		},
+	},
+	"extensions": {
+        "recommendations": [
+            // Rust:
+            "rust-lang.rust-analyzer",
+            "bungcip.better-toml",
+            "serayuzgur.crates",
+            // Misc:
+            "eamodio.gitlens",
+            // Nix:
+            "jnoortheen.nix-ide",
+            "mkhl.direnv"
+        ]
+    },
+	"tasks": {
+		"version": "2.0.0",
+		"tasks": [
+			{
+				"label": "Build All",
+				"type": "cargo",
+				"command": "b",
+				"problemMatcher": ["$rustc"],
+			},
+			{
+				"label": "Open Docs",
+				"type": "cargo",
+				"command": "d --open",
+				"problemMatcher": ["$rustc"],
+			},
+			{
+				"label": "Format Workspace",
+				"type": "cargo",
+				"command": "f",
+				"problemMatcher": ["$rustc"],
+			},
+			{
+				"label": "Test All",
+				"type": "cargo",
+				"command": "t",
+				"problemMatcher": ["$rustc"],
+			},
+			{
+				"label": "Lint All",
+				"type": "cargo",
+				"command": "l",
+				"problemMatcher": ["$rustc"],
+			},
+			{
+				"label": "Run Benchmarks",
+				"type": "cargo",
+				"command": "bench",
+				"problemMatcher": ["$rustc"],
+			}
+		]
+	},
+}
diff --git a/Cargo.toml b/Cargo.toml
@@ -12,8 +12,6 @@ members = [
     "test-infrastructure",
     "device-support" # TODO: spin off
 ]
-exclude = [ "misc/lc3-tm4c", "misc/serial" ] # TODO: remove
-
 
 [package] # TODO
 name = "lc3-utp"
@@ -29,10 +27,10 @@ lc3-os = { path = "os", version = "0.1.0" }
 
 lc3tools-sys = "=1.0.6-alpha2" # We can use the next point release (TODO).
 
-criterion = "0.3.0"
-async-std = "1.4.0"
-lazy_static = "1.4.0"
-pretty_assertions = "0.6.1"
+criterion = { version = "0.3", features = ["html_reports"] }
+async-std = "1.4"
+lazy_static = "1.4"
+pretty_assertions = "1.2"
 
 
 [[bench]]
@@ -50,7 +48,6 @@ harness = false
 
 [features]
 default = []
-nightly = [] # For benchmarking.
 lto = ["lc3tools-sys/lto"] # For benchmarking.
 
 

diff --git a/README.md b/README.md
@@ -47,10 +47,29 @@ At the moment, the primary 'users' of the platform are the following:
 
 TODO: fill in
 
+To check that the project _will_ build:
+  - `cargo c` or `cargo check-all`
+
+To actually build the project:
+  - `cargo b` or `cargo build-all` to build everything
+  - `cargo build -p <crate name>` to build a particular crate
+    + i.e. `cargo build -p lc3-isa`
+
+To run the project's tests:
+  - `cargo t` or `cargo test-all` to run all the tests
+  - `cargo test -p <crate name>` to run a particular crate's tests
+
+To run the project's benchmarks:
+  - `cargo bench` to run them all
+  - `cargo bench --bench <benchmark name>` to run a particular benchmark
+
 To build the docs for the project:
   - `cargo +nightly docs` (`cargo-nightly docs` if using `nix`)
     + NOTE: this requires a nightly Rust toolchain!
-    + If you're on stable you can instead run: `cargo docs-stable` to get mostly identical output
+    + If you're on stable you can instead run: `cargo d` (or `cargo docs-stable`) to get mostly identical output
+
+To run the project's lints (that CI runs):
+  - `cargo lint`
 
 
 TODO:

diff --git a/application-support/Cargo.toml b/application-support/Cargo.toml
@@ -2,7 +2,7 @@
 name = "lc3-application-support"
 version = "0.1.0"
 authors = ["UT UTP <ut.utp.group@gmail.com>"]
-edition = "2018"
+edition = "2021"
 
 workspace = ".."
 
@@ -45,10 +45,11 @@ wasm-bindgen = "0.2"
 wasm-bindgen-futures = "0.4"
 
 [dev-dependencies]
-pretty_assertions = "0.6.1"
+pretty_assertions = "1.2"
 
 [package.metadata.docs.rs]
-# targets = [""]
-rustdoc-args = ["--cfg", "docs"]
+targets = ["x86_64-unknown-linux-gnu", "x86_64-apple-darwin", "x86_64-pc-windows-msvc", "wasm32-unknown-unknown", "thumbv7em-none-eabihf"]
+cargo-args = ["-Zunstable-options", "-Zrustdoc-scrape-examples=examples"]
+rustdoc-args = ["--cfg", "docs"] # "--scrape-tests"
 all-features = true
-# default-target = ""
+default-target = "x86_64-unknown-linux-gnu"
diff --git a/application-support/src/event_loop/mod.rs b/application-support/src/event_loop/mod.rs
@@ -125,8 +125,6 @@ specialize! {
     not: { mod not_wasm; }
 }
 
-use lc3_traits::control::Control;
-
 /*
 // To make sure that the `Backoff` interface is satisfied:
 #[doc(hidden)]