From c0481c97f3d740fb0e7a2852f670ee342456ca24 Mon Sep 17 00:00:00 2001 From: Andy Gauge Date: Mon, 17 Jul 2017 11:49:50 -0700 Subject: [PATCH 1/4] Added hyperlinks to internal methods/structs/functions within docs. --- src/lib.rs | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index d156fe0..f485e41 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -10,12 +10,15 @@ //! //! The purpose of this crate is to provide the utility functions necessary to //! compile C code into a static archive which is then linked into a Rust crate. -//! The top-level `compile_library` function serves as a convenience and more -//! advanced configuration is available through the `Config` builder. +//! The top-level [`compile_library`] function serves as a convenience. More +//! advanced configuration is available through the [`Config`] builder. //! //! This crate will automatically detect situations such as cross compilation or //! other environment variables set by Cargo and will build code appropriately. //! +//! [`compile_library`]: fn.compile_library.html +//! [`Config`]: struct.Config.html +//! //! # Examples //! //! Use the default configuration: @@ -181,7 +184,9 @@ pub fn compile_library(output: &str, files: &[&str]) { impl Config { /// Construct a new instance of a blank set of configuration. /// - /// This builder is finished with the `compile` function. + /// This builder is finished with the [`compile`] function. + /// + /// [`compile`]: struct.Config.html#method.compile pub fn new() -> Config { Config { include_directories: Vec::new(), @@ -392,7 +397,7 @@ impl Config { /// /// This option is automatically scraped from the `HOST` environment /// variable by build scripts, so it's not required to call this function. - /// + /// /// # Example /// /// ```no_run From 89a9d3dfce2abb42d7dea72badc24d0a75a99145 Mon Sep 17 00:00:00 2001 From: Andy Gauge Date: Tue, 18 Jul 2017 09:32:16 -0700 Subject: [PATCH 2/4] Changed compile to accept name of library and updated examples --- src/lib.rs | 31 +++++++++++++++++-------------- 1 file changed, 17 insertions(+), 14 deletions(-) diff --git a/src/lib.rs b/src/lib.rs index d156fe0..5f72db8 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -24,7 +24,7 @@ //! extern crate gcc; //! //! fn main() { -//! gcc::compile_library("libfoo.a", &["src/foo.c"]); +//! gcc::compile_library("foo", &["src/foo.c"]); //! } //! ``` //! @@ -38,7 +38,7 @@ //! .file("src/foo.c") //! .define("FOO", Some("bar")) //! .include("src") -//! .compile("libfoo.a"); +//! .compile("foo"); //! } //! ``` @@ -168,7 +168,7 @@ impl ToolFamily { /// # Example /// /// ```no_run -/// gcc::compile_library("libfoo.a", &["foo.c", "bar.c"]); +/// gcc::compile_library("foo", &["foo.c", "bar.c"]); /// ``` pub fn compile_library(output: &str, files: &[&str]) { let mut c = Config::new(); @@ -221,7 +221,7 @@ impl Config { /// .file("src/foo.c") /// .include(library_path) /// .include("src") - /// .compile("libfoo.a"); + /// .compile("foo"); /// ``` pub fn include>(&mut self, dir: P) -> &mut Config { self.include_directories.push(dir.as_ref().to_path_buf()); @@ -237,7 +237,7 @@ impl Config { /// .file("src/foo.c") /// .define("FOO", Some("BAR")) /// .define("BAZ", None) - /// .compile("libfoo.a"); + /// .compile("foo"); /// ``` pub fn define(&mut self, var: &str, val: Option<&str>) -> &mut Config { self.definitions.push((var.to_string(), val.map(|s| s.to_string()))); @@ -258,7 +258,7 @@ impl Config { /// gcc::Config::new() /// .file("src/foo.c") /// .flag("-ffunction-sections") - /// .compile("libfoo.a"); + /// .compile("foo"); /// ``` pub fn flag(&mut self, flag: &str) -> &mut Config { self.flags.push(flag.to_string()); @@ -296,7 +296,7 @@ impl Config { /// .file("src/foo.c") /// .shared_flag(true) /// .static_flag(true) - /// .compile("libfoo.so"); + /// .compile("foo"); /// ``` pub fn static_flag(&mut self, static_flag: bool) -> &mut Config { self.static_flag = Some(static_flag); @@ -381,7 +381,7 @@ impl Config { /// gcc::Config::new() /// .file("src/foo.c") /// .target("aarch64-linux-android") - /// .compile("libfoo.so"); + /// .compile("foo"); /// ``` pub fn target(&mut self, target: &str) -> &mut Config { self.target = Some(target.to_string()); @@ -392,14 +392,14 @@ impl Config { /// /// This option is automatically scraped from the `HOST` environment /// variable by build scripts, so it's not required to call this function. - /// + /// /// # Example /// /// ```no_run /// gcc::Config::new() /// .file("src/foo.c") /// .host("arm-linux-gnueabihf") - /// .compile("libfoo.so"); + /// .compile("foo"); /// ``` pub fn host(&mut self, host: &str) -> &mut Config { self.host = Some(host.to_string()); @@ -500,11 +500,14 @@ impl Config { /// Run the compiler, generating the file `output` /// - /// The name `output` must begin with `lib` and end with `.a` + /// The name `output` should be the name of the library. For backwards compatibility, + /// the `output` may start with `lib` and end with `.a`. The Rust compilier will create + /// the assembly with the lib prefix and .a extension. MSVC will create a file without prefix, + /// ending with `.lib`. pub fn compile(&self, output: &str) { - assert!(output.starts_with("lib")); - assert!(output.ends_with(".a")); - let lib_name = &output[3..output.len() - 2]; + let name_start = if output.starts_with("lib") { 3 } else { 0 }; + let name_end = if output.ends_with(".a") { output.len() - 2 } else { output.len() }; + let lib_name = &output[name_start..name_end]; let dst = self.get_out_dir(); let mut objects = Vec::new(); From 87da1012e95022a1fe0732686a4579af20f963cc Mon Sep 17 00:00:00 2001 From: Andy Gauge Date: Tue, 18 Jul 2017 10:47:33 -0700 Subject: [PATCH 3/4] README has examples and documentation that is affected. --- README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 2d3e5ed..ae1f865 100644 --- a/README.md +++ b/README.md @@ -35,13 +35,14 @@ Next up, you'll want to write a build script like so: extern crate gcc; fn main() { - gcc::compile_library("libfoo.a", &["foo.c", "bar.c"]); + gcc::compile_library("foo", &["foo.c", "bar.c"]); } ``` And that's it! Running `cargo build` should take care of the rest and your Rust -application will now have the C files `foo.c` and `bar.c` compiled into it. You -can call the functions in Rust by declaring functions in your Rust code like so: +application will now have the C files `foo.c` and `bar.c` compiled into a file +named libfoo.a. You can call the functions in Rust by declaring functions in +your Rust code like so: ``` extern { From a7612851744678d26817d9cbc6efaed34acdba5d Mon Sep 17 00:00:00 2001 From: Ottavio Hartman Date: Tue, 18 Jul 2017 15:09:44 -0400 Subject: [PATCH 4/4] Remove compile_library function --- README.md | 4 +++- src/lib.rs | 17 ++++------------- 2 files changed, 7 insertions(+), 14 deletions(-) diff --git a/README.md b/README.md index 2d3e5ed..4c398f3 100644 --- a/README.md +++ b/README.md @@ -35,7 +35,9 @@ Next up, you'll want to write a build script like so: extern crate gcc; fn main() { - gcc::compile_library("libfoo.a", &["foo.c", "bar.c"]); + gcc::Config::new() + .files(["foo.c", "bar.c"]) + .compile("libfoo.a"); } ``` diff --git a/src/lib.rs b/src/lib.rs index d156fe0..84186df 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -10,25 +10,14 @@ //! //! The purpose of this crate is to provide the utility functions necessary to //! compile C code into a static archive which is then linked into a Rust crate. -//! The top-level `compile_library` function serves as a convenience and more -//! advanced configuration is available through the `Config` builder. +//! Configuration is available through the `Config` builder. //! //! This crate will automatically detect situations such as cross compilation or //! other environment variables set by Cargo and will build code appropriately. //! //! # Examples //! -//! Use the default configuration: -//! -//! ```no_run -//! extern crate gcc; -//! -//! fn main() { -//! gcc::compile_library("libfoo.a", &["src/foo.c"]); -//! } -//! ``` -//! -//! Use more advanced configuration: +//! Use the `Config` builder to compile `src/foo.c`: //! //! ```no_run //! extern crate gcc; @@ -170,6 +159,8 @@ impl ToolFamily { /// ```no_run /// gcc::compile_library("libfoo.a", &["foo.c", "bar.c"]); /// ``` +#[deprecated] +#[doc(hidden)] pub fn compile_library(output: &str, files: &[&str]) { let mut c = Config::new(); for f in files.iter() {