Merge pull request #440 from fitzgen/build-profiles-toml-config

Add three build profiles and infrastructure for their toml config

Author: fitzgen

Cargo.lock

@@ -18,4 +18,5 @@
     - [`src/utils.rs`](./tutorial/template-deep-dive/src-utils-rs.md)
   - [Packaging and Publishing](./tutorial/packaging-and-publishing.md)
   - [Using your Library](./tutorial/using-your-library.md)
+- [`Cargo.toml` Configuration](./cargo-toml-configuration.md)
 - [Contributing](./contributing.md)

docs/src/SUMMARY.md

@@ -0,0 +1,29 @@
+# `Cargo.toml` Configuration
+
+`wasm-pack` can be configured via the `package.metadata.wasm-pack` key in
+`Cargo.toml`. Every option has a default, and is not required.
+
+There are three profiles: `dev`, `profiling`, and `release`. These correspond to
+the `--dev`, `--profiling`, and `--release` flags passed to `wasm-pack build`.
+
+The available configuration options and their default values are shown below:
+
+```toml
+[package.metadata.wasm-pack.profile.dev.wasm-bindgen]
+# Should we enable wasm-bindgen's debug assertions in its generated JS glue?
+debug-js-glue = true
+# Should wasm-bindgen demangle the symbols in the "name" custom section?
+demangle-name-section = true
+# Should we emit the DWARF debug info custom sections?
+dwarf-debug-info = false
+
+[package.metadata.wasm-pack.profile.profiling.wasm-bindgen]
+debug-js-glue = false
+demangle-name-section = true
+dwarf-debug-info = false
+
+[package.metadata.wasm-pack.profile.release.wasm-bindgen]
+debug-js-glue = false
+demangle-name-section = true
+dwarf-debug-info = false
+```

docs/src/cargo-toml-configuration.md

@@ -16,15 +16,28 @@ wasm-pack build examples/js-hello-world
 This path should point to a directory that contains a `Cargo.toml` file. If no
 path is given, the `build` command will run in the current directory.
 
-## Debug
+## Profile
 
-The init command accepts an optional `--debug` argument. This will build the
-output package using cargo's
-[default non-release profile][cargo-profile-sections-documentation]. Building
-this way is faster but applies few optimizations to the output, and enables
-debug assertions and other runtime correctness checks.
+The `build` command accepts an optional profile argument: one of `--dev`,
+`--profiling`, or `--release`. If none is supplied, then `--release` is used.
 
-The exact meaning of this flag may evolve as the platform matures.
+Th controls whether debug assertions are enabled, debug info is generated, and
+which (if any) optimizations are enabled.
+
+| Profile       | Debug Assertions | Debug Info | Optimizations | Notes                                 |
+|---------------|------------------|------------|---------------|---------------------------------------|
+| `--dev`       | Yes              | Yes        | No            | Useful for development and debugging. |
+| `--profiling` | No               | Yes        | Yes           | Useful when profiling and investigating performance issues. |
+| `--release`   | No               | No         | Yes           | Useful for shipping to production.    |
+
+The `--dev` profile will build the output package using cargo's [default
+non-release profile][cargo-profile-sections-documentation]. Building this way is
+faster but applies few optimizations to the output, and enables debug assertions
+and other runtime correctness checks. The `--profiling` and `--release` profiles
+use cargo's release profile, but the former enables debug info as well, which
+helps when investigating performance issues in a profiler.
+
+The exact meaning of the profile flags may evolve as the platform matures.
 
 [cargo-profile-sections-documentation]: https://doc.rust-lang.org/cargo/reference/manifest.html#the-profile-sections
 

docs/src/commands/build.md

@@ -2,6 +2,7 @@
 
 use binaries::{Cache, Download};
 use child;
+use command::build::BuildProfile;
 use emoji;
 use failure::{self, ResultExt};
 use manifest::CrateData;
@@ -145,14 +146,17 @@ pub fn wasm_bindgen_build(
     out_dir: &Path,
     disable_dts: bool,
     target: &str,
-    debug: bool,
+    profile: BuildProfile,
     step: &Step,
     log: &Logger,
 ) -> Result<(), failure::Error> {
     let msg = format!("{}Running WASM-bindgen...", emoji::RUNNER);
     PBAR.step(step, &msg);
 
-    let release_or_debug = if debug { "debug" } else { "release" };
+    let release_or_debug = match profile {
+        BuildProfile::Release | BuildProfile::Profiling => "release",
+        BuildProfile::Dev => "debug",
+    };
 
     let out_dir = out_dir.to_str().unwrap();
 
@@ -181,9 +185,16 @@ pub fn wasm_bindgen_build(
         .arg(dts_arg)
         .arg(target_arg);
 
-    if debug {
+    let profile = data.configured_profile(profile);
+    if profile.wasm_bindgen_debug_js_glue() {
         cmd.arg("--debug");
     }
+    if !profile.wasm_bindgen_demangle_name_section() {
+        cmd.arg("--no-demangle");
+    }
+    if profile.wasm_bindgen_dwarf_debug_info() {
+        cmd.arg("--keep-debug");
+    }
 
     child::run(log, cmd, "wasm-bindgen").context("Running the wasm-bindgen CLI")?;
     Ok(())

src/bindgen.rs

@@ -1,6 +1,7 @@
 //! Building a Rust crate into a `.wasm` binary.
 
 use child;
+use command::build::BuildProfile;
 use emoji;
 use failure::{Error, ResultExt};
 use progressbar::Step;
@@ -62,13 +63,32 @@ pub fn rustup_add_wasm_target(log: &Logger, step: &Step) -> Result<(), Error> {
 }
 
 /// Run `cargo build` targetting `wasm32-unknown-unknown`.
-pub fn cargo_build_wasm(log: &Logger, path: &Path, debug: bool, step: &Step) -> Result<(), Error> {
+pub fn cargo_build_wasm(
+    log: &Logger,
+    path: &Path,
+    profile: BuildProfile,
+    step: &Step,
+) -> Result<(), Error> {
     let msg = format!("{}Compiling to WASM...", emoji::CYCLONE);
     PBAR.step(step, &msg);
     let mut cmd = Command::new("cargo");
     cmd.current_dir(path).arg("build").arg("--lib");
-    if !debug {
-        cmd.arg("--release");
+    match profile {
+        BuildProfile::Profiling => {
+            // Once there are DWARF debug info consumers, force enable debug
+            // info, because builds that use the release cargo profile disables
+            // debug info.
+            //
+            // cmd.env("RUSTFLAGS", "-g");
+            cmd.arg("--release");
+        }
+        BuildProfile::Release => {
+            cmd.arg("--release");
+        }
+        BuildProfile::Dev => {
+            // Plain cargo builds use the dev cargo profile, which includes
+            // debug info by default.
+        }
     }
     cmd.arg("--target").arg("wasm32-unknown-unknown");
     child::run(log, cmd, "cargo build").context("Compiling your crate to WebAssembly failed")?;

src/build.rs

@@ -25,9 +25,8 @@ pub struct Build {
     pub scope: Option<String>,
     pub disable_dts: bool,
     pub target: String,
-    pub debug: bool,
+    pub profile: BuildProfile,
     pub mode: BuildMode,
-    // build_config: Option<BuildConfig>,
     pub out_dir: PathBuf,
     pub bindgen: Option<Download>,
     pub cache: Cache,
@@ -64,6 +63,18 @@ impl FromStr for BuildMode {
     }
 }
 
+/// The build profile controls whether optimizations, debug info, and assertions
+/// are enabled or disabled.
+#[derive(Clone, Copy, Debug)]
+pub enum BuildProfile {
+    /// Enable assertions and debug info. Disable optimizations.
+    Dev,
+    /// Enable optimizations. Disable assertions and debug info.
+    Release,
+    /// Enable optimizations and debug info. Disable assertions.
+    Profiling,
+}
+
 /// Everything required to configure and run the `wasm-pack build` command.
 #[derive(Debug, StructOpt)]
 pub struct BuildOptions {
@@ -97,6 +108,14 @@ pub struct BuildOptions {
     /// optimizations.
     dev: bool,
 
+    #[structopt(long = "release")]
+    /// Create a release build. Enable optimizations and disable debug info.
+    release: bool,
+
+    #[structopt(long = "profiling")]
+    /// Create a profiling build. Enable optimizations and debug info.
+    profiling: bool,
+
     #[structopt(long = "out-dir", short = "d", default_value = "pkg")]
     /// Sets the output directory with a relative path.
     pub out_dir: String,
@@ -110,16 +129,25 @@ impl Build {
         let crate_path = set_crate_path(build_opts.path)?;
         let crate_data = manifest::CrateData::new(&crate_path)?;
         let out_dir = crate_path.join(PathBuf::from(build_opts.out_dir));
-        // let build_config = manifest::xxx(&crate_path).xxx();
+
+        let dev = build_opts.dev || build_opts.debug;
+        let profile = match (dev, build_opts.release, build_opts.profiling) {
+            (false, false, false) | (false, true, false) => BuildProfile::Release,
+            (true, false, false) => BuildProfile::Dev,
+            (false, false, true) => BuildProfile::Profiling,
+            // Unfortunately, `structopt` doesn't expose clap's `conflicts_with`
+            // functionality yet, so we have to implement it ourselves.
+            _ => bail!("Can only supply one of the --dev, --release, or --profiling flags"),
+        };
+
         Ok(Build {
             crate_path,
             crate_data,
             scope: build_opts.scope,
             disable_dts: build_opts.disable_dts,
             target: build_opts.target,
-            debug: build_opts.dev || build_opts.debug,
+            profile,
             mode: build_opts.mode,
-            // build_config,
             out_dir,
             bindgen: None,
             cache: Cache::new()?,
@@ -227,7 +255,7 @@ impl Build {
 
     fn step_build_wasm(&mut self, step: &Step, log: &Logger) -> Result<(), Error> {
         info!(&log, "Building wasm...");
-        build::cargo_build_wasm(log, &self.crate_path, self.debug, step)?;
+        build::cargo_build_wasm(log, &self.crate_path, self.profile, step)?;
 
         info!(
             &log,
@@ -302,7 +330,7 @@ impl Build {
             &self.out_dir,
             self.disable_dts,
             &self.target,
-            self.debug,
+            self.profile,
             step,
             log,
         )?;

src/command/build.rs

@@ -14,6 +14,7 @@ extern crate indicatif;
 #[macro_use]
 extern crate lazy_static;
 extern crate parking_lot;
+extern crate serde;
 #[macro_use]
 extern crate serde_derive;
 extern crate serde_json;