somedoc

Cargo.toml

@@ -1,7 +1,7 @@
 [workspace]
 members = [
     "cargo-dinghy",
-    "dinghy-helper",
+    "dinghy-build",
     "dinghy-lib",
     "dinghy-test",
 ]

dinghy-helper/Cargo.toml → dinghy-build/Cargo.toml

@@ -1,9 +1,9 @@
 [package]
-name = "dinghy-helper"
+name = "dinghy-build"
 version = "0.3.0-pre"
 authors = ["Mathieu Poumeyrol <[email protected]>"]
 license = "MIT/Apache-2.0"
-description = "Painless tests on mobile devices"
+description = "Cross-compilation made easier - helpers for build.rs scripts"
 homepage = "https://medium.com/snips-ai/dinghy-painless-rust-tests-and-benches-on-ios-and-android-c9f94f81d305#.c2sx7two8"
 repository = "https://github.com/snipsco/dinghy"
 keywords = [

dinghy-helper/src/build.rs → dinghy-build/src/build.rs

@@ -1,38 +1,46 @@
+///! Helpers functions to output `cargo:` lines  suitable for build.rs output.
 use std::env;
 use std::path::Path;
 use super::Result;
 
+/// Find out if we are cross-compiling.
 pub fn is_cross_compiling() -> Result<bool> {
     Ok(env::var("TARGET")? != env::var("HOST")?)
 }
 
+/// Adds a `cargo:rustc-link-lib=` line.
 pub fn include_path<P: AsRef<Path>>(lib_dir_path: P) -> Result<()> {
     println!("cargo:rustc-link-lib={}", lib_dir_path.as_ref().display());
     Ok(())
 }
 
+/// Adds a `cargo:rustc-link-search=` and `cargo:rustc-link-lib=dylib=` line.
 pub fn link_dylib<P: AsRef<Path>>(lib_name: &str, lib_dir_path: P) -> Result<()> {
     println!("cargo:rustc-link-search={}", lib_dir_path.as_ref().display());
     println!("cargo:rustc-link-lib=dylib={}", lib_name);
     Ok(())
 }
 
+/// Adds a `cargo:rustc-link-search` and `cargo:rustc-link-lib=` line.
 pub fn link_lib<P: AsRef<Path>>(lib_name: &str, lib_dir_path: P) -> Result<()> {
     println!("cargo:rustc-link-search={}", lib_dir_path.as_ref().display());
     println!("cargo:rustc-link-lib={}", lib_name);
     Ok(())
 }
 
+/// Adds a `cargo:rustc-link-lib=dylib=` line.
 pub fn link_system_dylib(lib_name: &str) -> Result<()> {
     println!("cargo:rustc-link-lib=dylib={}", lib_name);
     Ok(())
 }
 
+/// Adds a `cargo:rustc-link-lib=` line.
 pub fn link_system_lib(lib_name: &str) -> Result<()> {
     println!("cargo:rustc-link-lib={}", lib_name);
     Ok(())
 }
 
+/// Adds a `cargo:rerun-if-changed=` line.
 pub fn rerun_if_changed<P: AsRef<Path>>(filepath: P) {
     println!("cargo:rerun-if-changed={}", filepath.as_ref().display());
 }

dinghy-helper/src/build_env.rs → dinghy-build/src/build_env.rs

@@ -1,10 +1,27 @@
+//! Target-aware environment manipulations.
+//!
+//! cc-rs and pkg-config-rs use a similar convention where some environment
+//! variables (like CC, CFLAGS or PKG_CONFIG_PATH) can be tagged with the
+//! current rustc target to distinguish a native build environment and one
+//! or several cross-compilation ones.
+//!
+//! For instance, while compiling for Android arm, `cc-rs` looks first at 
+//! CC_arm-linux-androideabi, then CC_arm_linux_androideabi, the TARGET_CC
+//! and finally CC.
+//!
+//! This crates implements some of the same logic and also helps generating
+//! these variables names. It also notify all environment lookup "back" to 
+//! cargo using `cargo:rerun-if-env-changed` markup.
+
 use std::env;
 use std::ffi::OsStr;
 use std::ffi::OsString;
 use std::path::PathBuf;
 use super::Result;
 use super::ResultExt;
 
+
+/// Append a value to a PATH-like (`:`-separated) environment variable.
 pub fn append_path_to_env<K: AsRef<OsStr>, V: AsRef<OsStr>>(key: K, value: V) {
     debug!("Appending {:?} to {:?}", value.as_ref(), key.as_ref());
     let mut formatted_value = OsString::new();
@@ -16,11 +33,17 @@ pub fn append_path_to_env<K: AsRef<OsStr>, V: AsRef<OsStr>>(key: K, value: V) {
     env::set_var(key.as_ref(), formatted_value);
 }
 
+/// Append a value to a PATH-like (`:`-separated) environment variable taking
+/// target scoping rules into consideration.
 pub fn append_path_to_target_env<K: AsRef<OsStr>, R: AsRef<str>, V: AsRef<OsStr>>(
     k: K, rustc_triple: Option<R>, v: V) {
     append_path_to_env(target_key_from_triple(k, rustc_triple), v.as_ref())
 }
 
+/// Build-context aware environment variable access.
+///
+/// If we are running in a build.rs context, register the var to cargo using
+/// `cargo:rerun-if-env-changed`.
 pub fn build_env(name: &str) -> Result<String> {
     let is_build_rs = env::var("CARGO_PKG_NAME").is_ok() && env::var("OUT_DIR").is_ok();
 
@@ -30,6 +53,7 @@ pub fn build_env(name: &str) -> Result<String> {
     Ok(env::var(name)?)
 }
 
+/// Capitalize and replace `-` by `_`.
 pub fn envify<S: AsRef<str>>(name: S) -> String {
     name.as_ref()
         .chars()
@@ -38,17 +62,20 @@ pub fn envify<S: AsRef<str>>(name: S) -> String {
         .collect()
 }
 
+/// Set a bunch of environment variables.
 pub fn set_all_env<K: AsRef<OsStr>, V: AsRef<OsStr>>(env: &[(K, V)]) {
     for env_var in env {
         set_env(env_var.0.as_ref(), env_var.1.as_ref())
     }
 }
 
+/// Set one environment variable.
 pub fn set_env<K: AsRef<OsStr>, V: AsRef<OsStr>>(k: K, v: V) {
     debug!("Setting environment variable {:?}={:?}", k.as_ref(), v.as_ref());
     env::set_var(k, v);
 }
 
+/// Set one environment variable if not set yet.
 pub fn set_env_ifndef<K: AsRef<OsStr>, V: AsRef<OsStr>>(k: K, v: V) {
     if let Ok(current_env_value) = env::var(k.as_ref()) {
         debug!("Ignoring value {:?} as environment variable {:?} already defined with value {:?}",
@@ -59,14 +86,19 @@ pub fn set_env_ifndef<K: AsRef<OsStr>, V: AsRef<OsStr>>(k: K, v: V) {
     }
 }
 
+/// Set one environment variable with target-scoping rules.
 pub fn set_target_env<K: AsRef<OsStr>, R: AsRef<str>, V: AsRef<OsStr>>(k: K, rustc_triple: Option<R>, v: V) {
     set_env(target_key_from_triple(k, rustc_triple), v);
 }
 
+/// Access a required TARGET_SYSROOT variable, suggesting to define it or use
+/// Dinghy.
 pub fn sysroot_path() -> Result<PathBuf> {
     env::var_os("TARGET_SYSROOT").map(PathBuf::from).chain_err(|| "You must either define a TARGET_SYSROOT or use Dinghy to build your project.")
 }
 
+/// Access `var_base` directly, or use targetting rules depending on the build
+/// being native or cross.
 pub fn target_env(var_base: &str) -> Result<String> {
     if let Ok(target) = env::var("TARGET") {
         let is_host = env::var("HOST")? == target;
@@ -76,6 +108,7 @@ pub fn target_env(var_base: &str) -> Result<String> {
     }
 }
 
+/// Access `var_base` directly, using targetting rules.
 pub fn target_env_from_triple(var_base: &str, triple: &str, is_host: bool) -> Result<String> {
     build_env(&format!("{}_{}", var_base, triple))
         .or_else(|_| build_env(&format!("{}_{}", var_base, triple.replace("-", "_"))))

dinghy-helper/src/lib.rs → dinghy-build/src/lib.rs

@@ -1,3 +1,12 @@
+//! Helpers for build.rs scripts.
+//!
+//! This library is meant to be used in build.rs scripts context.
+//!
+//! It contains a set of standalone functions that encodes some of the
+//! shared wisdom and conventions across build.rs scripts, cargo, dinghy,
+//! cc-rs, pkg-config-rs, bindgen, and others. It also helps providing
+//! cross-compilation arguments to autotools `./configure` scripts.
+
 extern crate bindgen;
 #[macro_use]
 extern crate error_chain;
@@ -29,13 +38,25 @@ error_chain! {
     }
 }
 
+/// Decorator for the std::process::Command adding a some chainable helpers.
+/// 
+/// Mostly useful for calling `./configure` scripts.
 pub trait CommandExt {
+    /// Add this argument to the commands, but only on macos.
     fn arg_for_macos<S: AsRef<OsStr>>(&mut self, arg: S) -> Result<&mut Command>;
 
+    /// Add a `--prefix` to point to a toolchain sysroot or the /, depending on
+    /// dinghy environment.
     fn configure_prefix<P: AsRef<Path>>(&mut self, path: P) -> Result<&mut Command>;
 
+    /// Adds pkgconfig environment variables to point to an eventual cross compiling sysroot.
+    ///
+    /// Usefull for compatibilty with pkg-config-rs up to 0.3.9 or to deal with
+    /// `./configure` scripts.
     fn with_pkgconfig(&mut self) -> Result<&mut Command>;
 
+    /// Propagate TARGET, TARGET_CC, TARGET_AR and TARGET_SYSROOT to a
+    /// `./configure` script.
     fn with_toolchain(&mut self) -> Result<&mut Command>;
 }
 

dinghy-helper/src/utils.rs → dinghy-build/src/utils.rs

@@ -1,11 +1,15 @@
+//! Some helpers around Path and PathBuf manipulations.
+
 use std::path::Path;
 use std::path::PathBuf;
 use super::Result;
 
+/// Wraps the annoying PathBuf to string conversion in one single call.
 pub fn path_to_str(path: &PathBuf) -> Result<&str> {
     Ok(path.to_str().ok_or(format!("Not a valid UTF-8 path ({})", path.display()))?)
 }
 
+/// Finds the path to `to` relative from `from`.
 pub fn path_between<P1: AsRef<Path>, P2: AsRef<Path>>(from: P1, to: P2) -> PathBuf {
     let mut path = PathBuf::from("/");
     for _ in from.as_ref() {

dinghy-lib/Cargo.toml

@@ -13,7 +13,7 @@ build="build.rs"
 categories = [ "development-tools::cargo-plugins", "development-tools::testing" , "development-tools::profiling" ]
 
 [dependencies]
-dinghy-helper = { path = "../dinghy-helper" }
+dinghy-build = { path = "../dinghy-build" }
 error-chain = "0.11"
 filetime = "0.1"
 log="0.3"

dinghy-lib/src/compiler.rs

@@ -13,7 +13,7 @@ use cargo::ops as CargoOps;
 use cargo::ops::TestOptions;
 use cargo::util::config::Config as CompileConfig;
 use clap::ArgMatches;
-use dinghy_helper::build_env::target_env_from_triple;
+use dinghy_build::build_env::target_env_from_triple;
 use itertools::Itertools;
 use std::collections::HashSet;
 use std::env;

dinghy-lib/src/device/host.rs

@@ -1,5 +1,5 @@
 use compiler::Compiler;
-use dinghy_helper::build_env::set_env;
+use dinghy_build::build_env::set_env;
 use itertools::Itertools;
 use platform::host::HostPlatform;
 use project::Project;

dinghy-lib/src/lib.rs

@@ -4,7 +4,7 @@ extern crate clap;
 extern crate core_foundation;
 #[cfg(target_os = "macos")]
 extern crate core_foundation_sys;
-extern crate dinghy_helper;
+extern crate dinghy_build;
 #[macro_use]
 extern crate error_chain;
 extern crate filetime;

dinghy-lib/src/overlay.rs

@@ -1,8 +1,8 @@
 use config::PlatformConfiguration;
-use dinghy_helper::build_env::append_path_to_target_env;
-use dinghy_helper::build_env::envify;
-use dinghy_helper::build_env::set_env_ifndef;
-use dinghy_helper::utils::path_between;
+use dinghy_build::build_env::append_path_to_target_env;
+use dinghy_build::build_env::envify;
+use dinghy_build::build_env::set_env_ifndef;
+use dinghy_build::utils::path_between;
 use errors::*;
 use itertools::Itertools;
 use project::Project;

dinghy-lib/src/platform/host.rs

@@ -1,6 +1,6 @@
 use compiler::Compiler;
 use config::PlatformConfiguration;
-use dinghy_helper::build_env::set_all_env;
+use dinghy_build::build_env::set_all_env;
 use overlay::Overlayer;
 use platform;
 use project::Project;

dinghy-lib/src/platform/ios.rs

@@ -1,6 +1,6 @@
 use compiler::Compiler;
 use config::PlatformConfiguration;
-use dinghy_helper::build_env::set_env;
+use dinghy_build::build_env::set_env;
 use errors::*;
 use overlay::Overlayer;
 use project::Project;

dinghy-lib/src/platform/regular_platform.rs

@@ -1,4 +1,4 @@
-use dinghy_helper::build_env::set_all_env;
+use dinghy_build::build_env::set_all_env;
 use overlay::Overlayer;
 use platform;
 use project::Project;

dinghy-lib/src/toolchain.rs

@@ -1,9 +1,9 @@
 use cargo::util::important_paths::find_root_manifest_for_wd;
-use dinghy_helper::build_env::append_path_to_target_env;
-use dinghy_helper::build_env::append_path_to_env;
-use dinghy_helper::build_env::envify;
-use dinghy_helper::build_env::set_env;
-use dinghy_helper::build_env::set_target_env;
+use dinghy_build::build_env::append_path_to_target_env;
+use dinghy_build::build_env::append_path_to_env;
+use dinghy_build::build_env::envify;
+use dinghy_build::build_env::set_env;
+use dinghy_build::build_env::set_target_env;
 use errors::*;
 use itertools::Itertools;
 use std::{env, fs, path};