Document CXXSTDLIB and change the Android default (#561)

* Change default C++ stdlib for Android to c++_shared and document it

Closes #559.

* Clean up documentation

Author: alexeyr

README.md

@@ -33,19 +33,31 @@ fn main() {
 
 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 a file
-named libfoo.a. You can call the functions in Rust by declaring functions in
+named `libfoo.a`. If the C files contain
+
+```c
+void foo_function(void) { ... }
+```
+
+and
+
+```c
+int32_t bar_function(int32_t x) { ... }
+```
+
+you can call them from Rust by declaring them in
 your Rust code like so:
 
 ```rust,no_run
 extern {
     fn foo_function();
-    fn bar_function();
+    fn bar_function(x: i32) -> i32;
 }
 
 pub fn call() {
     unsafe {
         foo_function();
-        bar_function();
+        bar_function(42);
     }
 }
 
@@ -54,14 +66,16 @@ fn main() {
 }
 ```
 
+See [the Rustonomicon](https://doc.rust-lang.org/nomicon/ffi.html) for more details.
+
 ## External configuration via environment variables
 
 To control the programs and flags used for building, the builder can set a
 number of different environment variables.
 
 * `CFLAGS` - a series of space separated flags passed to compilers. Note that
              individual flags cannot currently contain spaces, so doing
-             something like: "-L=foo\ bar" is not possible.
+             something like: `-L=foo\ bar` is not possible.
 * `CC` - the actual C compiler used. Note that this is used as an exact
          executable name, so (for example) no extra flags can be passed inside
          this variable, and the builder must ensure that there aren't any
@@ -70,6 +84,7 @@ number of different environment variables.
          common is `-fPIC`).
 * `AR` - the `ar` (archiver) executable to use to build the static library.
 * `CRATE_CC_NO_DEFAULTS` - the default compiler flags may cause conflicts in some cross compiling scenarios. Setting this variable will disable the generation of default compiler flags.
+* `CXX...` - see [C++ Support](#c-support).
 
 Each of these variables can also be supplied with certain prefixes and suffixes,
 in the following prioritized order:
@@ -144,10 +159,25 @@ fn main() {
 }
 ```
 
-When using C++ library compilation switch, the `CXX` and `CXXFLAGS` env
-variables are used instead of `CC` and `CFLAGS` and the C++ standard library is
-linked to the crate target.
-Remember that C++ does name mangling so `extern "C"` might be required to enable rust linker to find your functions.
+For C++ libraries, the `CXX` and `CXXFLAGS` environment variables are used instead of `CC` and `CFLAGS`.
+
+The C++ standard library may be linked to the crate target. By default it's `libc++` for OS X, FreeBSD, and OpenBSD, `libc++_shared` for Android, nothing for MSVC, and `libstdc++` for anything else. It can be changed in one of two ways:
+
+1. by using the `cpp_link_stdlib` method on `Build`:
+    ```rust,no-run
+    fn main() {
+        cc::Build::new()
+            .cpp(true)
+            .file("foo.cpp")
+            .cpp_link_stdlib("stdc++") // use libstdc++
+            .compile("libfoo.a");
+    }
+    ```
+2. by setting the `CXXSTDLIB` environment variable.
+
+In particular, for Android you may want to [use `c++_static` if you have at most one shared library](https://developer.android.com/ndk/guides/cpp-support).
+
+Remember that C++ does name mangling so `extern "C"` might be required to enable Rust linker to find your functions.
 
 ## CUDA C++ support
 

src/lib.rs

@@ -81,7 +81,7 @@ mod setup_config;
 
 pub mod windows_registry;
 
-/// A builder for compilation of a native static library.
+/// A builder for compilation of a native library.
 ///
 /// A `Build` is the main type of the `cc` crate and is used to control all the
 /// various configuration options and such of a compile. You'll find more
@@ -684,11 +684,11 @@ impl Build {
     /// Set the standard library to link against when compiling with C++
     /// support.
     ///
-    /// The default value of this property depends on the current target: On
-    /// OS X `Some("c++")` is used, when compiling for a Visual Studio based
-    /// target `None` is used and for other targets `Some("stdc++")` is used.
+    /// See [`get_cpp_link_stdlib`](cc::Build::get_cpp_link_stdlib) documentation
+    /// for the default value.
     /// If the `CXXSTDLIB` environment variable is set, its value will
-    /// override the default value.
+    /// override the default value, but not the value explicitly set by calling
+    /// this function.
     ///
     /// A value of `None` indicates that no automatic linking should happen,
     /// otherwise cargo will link against the specified library.
@@ -698,6 +698,7 @@ impl Build {
     /// Common values:
     /// - `stdc++` for GNU
     /// - `c++` for Clang
+    /// - `c++_shared` or `c++_static` for Android
     ///
     /// # Example
     ///
@@ -2241,8 +2242,11 @@ impl Build {
         ))
     }
 
-    /// Returns the default C++ standard library for the current target: `libc++`
-    /// for OS X and `libstdc++` for anything else.
+    /// Returns the C++ standard library:
+    /// 1. If [cpp_link_stdlib](cc::Build::cpp_link_stdlib) is set, uses its value.
+    /// 2. Else if the `CXXSTDLIB` environment variable is set, uses its value.
+    /// 3. Else the default is `libc++` for OS X and BSDs, `libc++_shared` for Android,
+    /// `None` for MSVC and `libstdc++` for anything else.
     fn get_cpp_link_stdlib(&self) -> Result<Option<String>, Error> {
         match self.cpp_link_stdlib.clone() {
             Some(s) => Ok(s),
@@ -2263,6 +2267,8 @@ impl Build {
                         Ok(Some("c++".to_string()))
                     } else if target.contains("openbsd") {
                         Ok(Some("c++".to_string()))
+                    } else if target.contains("android") {
+                        Ok(Some("c++_shared".to_string()))
                     } else {
                         Ok(Some("stdc++".to_string()))
                     }