From 55282f871e4fb5755e792999917909e57d3b2f2e Mon Sep 17 00:00:00 2001 From: Ed Morley <501702+edmorley@users.noreply.github.com> Date: Thu, 7 Jul 2022 09:33:25 +0100 Subject: [PATCH 1/2] Add missing crate READMEs and other cleanup * Adds READMEs for the `libcnb-data` and `libcnb-proc-macros` crates, since previously they were bundling the repo root README, which was confusing when looking at their crates.io listing (#274). * Corrects the MSRV listed in the READMEs so it matches that defined in each crate's `Cargo.toml` after #445. * Adds badges to READMEs that didn't have them, to improve discoverability of the docs (eg towards #402) and awareness of latest version of each crate. Note: `libcnb-cargo` does not have a docs link since it's a binary not a library. * Syncs the `libcnb-cargo` usage example output with the latest output used in the repo root README. * Switches the docs.rs URLs style from `/*/` to `/latest/` since the former resolves to an exact version, which if bookmarked (or search engine indexed) will get out of date. * Various other small tweaks. Fixes #274. Addresses part of #402. --- README.md | 25 +++++++++++-------------- libcnb-cargo/README.md | 19 ++++++++++++------- libcnb-data/Cargo.toml | 4 ++-- libcnb-data/README.md | 14 ++++++++++++++ libcnb-package/README.md | 10 ++++------ libcnb-proc-macros/Cargo.toml | 4 ++-- libcnb-proc-macros/README.md | 13 +++++++++++++ libcnb-test/README.md | 9 ++++++++- 8 files changed, 66 insertions(+), 32 deletions(-) create mode 100644 libcnb-data/README.md create mode 100644 libcnb-proc-macros/README.md diff --git a/README.md b/README.md index 8383e0f0..142507d9 100644 --- a/README.md +++ b/README.md @@ -1,13 +1,13 @@ -# libcnb.rs [![Build Status]][ci] [![Docs]][docs.rs] [![Latest Version]][crates.io] [![Rustc Version 1.58+]][rustc] +# libcnb.rs   [![Build Status]][ci] [![Docs]][docs.rs] [![Latest Version]][crates.io] [![MSRV]][install-rust] [Build Status]: https://img.shields.io/github/workflow/status/heroku/libcnb.rs/CI/main [ci]: https://github.com/heroku/libcnb.rs/actions/workflows/ci.yml?query=branch%3Amain [Docs]: https://img.shields.io/docsrs/libcnb -[docs.rs]: https://docs.rs/libcnb/*/libcnb/ +[docs.rs]: https://docs.rs/libcnb/latest/libcnb/ [Latest Version]: https://img.shields.io/crates/v/libcnb.svg [crates.io]: https://crates.io/crates/libcnb -[Rustc Version 1.58+]: https://img.shields.io/badge/rustc-1.58+-lightgray.svg -[rustc]: https://blog.rust-lang.org/2022/01/13/Rust-1.58.0.html +[MSRV]: https://img.shields.io/badge/MSRV-rustc_1.59+-lightgray.svg +[install-rust]: https://www.rust-lang.org/tools/install `libcnb.rs` is a framework for writing [Cloud Native Buildpacks](https://buildpacks.io) in Rust. It is an opinionated implementation adding language constructs and convenience methods for working with the spec. It values strong adherence to the spec and data formats. @@ -33,9 +33,9 @@ $ cargo install libcnb-cargo #### Cross-compilation prerequisites -It is common to write and build your buildpack on a platform that is different from the platform the buildpack will -eventually run on. This means we have to cross-compile our buildpack. The `libcnb package` Cargo command tries to help you setting -up your environment depending on your host platform, but we always need the appropriate target platform for Rust which +It is common to write and build your buildpack on a platform that is different from the platform on which the buildpack will +eventually run. This means we have to cross-compile our buildpack. The `libcnb package` Cargo command tries to help you set +up your environment depending on your host platform, but we always need the appropriate target platform for Rust, which we can install with `rustup`: ```shell @@ -89,8 +89,8 @@ id = "*" That's all we need! We can now move on to finally write some buildpack code! - ### Writing the Buildpack + As aforementioned, the buildpack we're writing will be very simple. We will just log a "Hello World" message during the build and set the default process type to a command that will also emit "Hello World" when the application image is run. Find more complex example buildpacks in the [examples directory](examples). @@ -199,12 +199,7 @@ application code at all, we just create an empty directory and use that as our a ```shell $ mkdir bogus-app $ pack build my-image --buildpack target/buildpack/debug/libcnb-examples_my-buildpack --path bogus-app --builder heroku/builder:22 -22: Pulling from heroku/builder -Digest: sha256:0e1db52b480805c63b793a1c0155ea30cabffbf7977f722c88dc42cef750a1d1 -Status: Image is up to date for heroku/builder:22 -22-cnb: Pulling from heroku/heroku -Digest: sha256:3fd7866f22dcbcd3a72c7ab4b47728dcfbaacfa9730341d0fb10665f63d93788 -Status: Image is up to date for heroku/heroku:22-cnb +... ===> ANALYZING Previous image with name "my-image" not found ===> DETECTING @@ -230,6 +225,7 @@ Successfully built image my-image ``` ### Running the image + The newly created Docker image can be run in the same way as you would a Docker image created via `docker build`. If all went well, you should see our "Hello World!" message in your terminal: @@ -239,6 +235,7 @@ Hello World! ``` ### Next Steps + While the buildpack we've written in this quick start guide is not very useful, it can serve as a starting point for a more useful buildpack. To discover more of the libcnb API, browse the [examples directory](examples) and the [documentation on docs.rs][docs.rs]. diff --git a/libcnb-cargo/README.md b/libcnb-cargo/README.md index 7b073f91..0648e1cd 100644 --- a/libcnb-cargo/README.md +++ b/libcnb-cargo/README.md @@ -1,6 +1,6 @@ -# libcnb-cargo +# libcnb-cargo   [![Latest Version]][crates.io] [![MSRV]][install-rust] -Cargo command for managing buildpacks written with [libcnb.rs](https://github.com/heroku/libcnb.rs). +A Cargo command for managing buildpacks written with [libcnb.rs](https://github.com/heroku/libcnb.rs). ## Installation @@ -18,12 +18,17 @@ project directory: $ cargo libcnb package INFO - Reading buildpack metadata... INFO - Found buildpack libcnb-examples/my-buildpack with version 0.1.0. -INFO - Building buildpack binary (x86_64-unknown-linux-musl)... -Compiling my-buildpack v0.1.0 (/Users/manuel.fuchs/projects/my-buildpack) +INFO - Determining automatic cross-compile settings... +INFO - Building binaries (x86_64-unknown-linux-musl)... # Omitting compilation output... -Finished dev [unoptimized + debuginfo] target(s) in 2.67s + Finished dev [unoptimized + debuginfo] target(s) in 4.29s INFO - Writing buildpack directory... -INFO - Successfully wrote buildpack directory: target/debug/libcnb-examples_my-buildpack_0.1.0 (53.1M) +INFO - Successfully wrote buildpack directory: target/buildpack/debug/libcnb-examples_my-buildpack (3.26 MiB) INFO - Packaging successfully finished! -INFO - Hint: To test your buildpack locally with pack, run: pack build my-image --buildpack target/debug/libcnb-examples_my-buildpack_0.1.0 --path /path/to/application +INFO - Hint: To test your buildpack locally with pack, run: pack build my-image --buildpack target/buildpack/debug/libcnb-examples_my-buildpack --path /path/to/application ``` + +[Latest Version]: https://img.shields.io/crates/v/libcnb-cargo.svg +[crates.io]: https://crates.io/crates/libcnb-cargo +[MSRV]: https://img.shields.io/badge/MSRV-rustc_1.59+-lightgray.svg +[install-rust]: https://www.rust-lang.org/tools/install diff --git a/libcnb-data/Cargo.toml b/libcnb-data/Cargo.toml index d88a1f86..8ab1d93c 100644 --- a/libcnb-data/Cargo.toml +++ b/libcnb-data/Cargo.toml @@ -8,8 +8,8 @@ description = "Types for data formats specified in the Cloud Native Buildpack sp keywords = ["buildpacks", "CNB"] repository = "https://github.com/heroku/libcnb.rs/tree/main/libcnb-data" documentation = "https://docs.rs/libcnb-data" -readme = "../README.md" -include = ["src/**/*", "../LICENSE", "../README.md"] +readme = "README.md" +include = ["src/**/*", "../LICENSE", "README.md"] [dependencies] fancy-regex = { version = "0.10.0", default-features = false } diff --git a/libcnb-data/README.md b/libcnb-data/README.md new file mode 100644 index 00000000..2e9874bb --- /dev/null +++ b/libcnb-data/README.md @@ -0,0 +1,14 @@ +# libcnb-data   [![Docs]][docs.rs] [![Latest Version]][crates.io] [![MSRV]][install-rust] + +Provides types for data formats specified in the Cloud Native Buildpack specification. + +If you wish to create buildpacks using the [libcnb.rs](https://github.com/heroku/libcnb.rs) +framework, use the [libcnb](https://crates.io/crates/libcnb) crate rather than depending +on this crate directly. + +[Docs]: https://img.shields.io/docsrs/libcnb-data +[docs.rs]: https://docs.rs/libcnb-data/latest/libcnb_data/ +[Latest Version]: https://img.shields.io/crates/v/libcnb-data.svg +[crates.io]: https://crates.io/crates/libcnb-data +[MSRV]: https://img.shields.io/badge/MSRV-rustc_1.59+-lightgray.svg +[install-rust]: https://www.rust-lang.org/tools/install diff --git a/libcnb-package/README.md b/libcnb-package/README.md index 46a19fe1..fd084df1 100644 --- a/libcnb-package/README.md +++ b/libcnb-package/README.md @@ -1,6 +1,4 @@ -# libcnb-package - -[![Docs]][docs.rs] [![Latest Version]][crates.io] [![Rustc Version 1.58+]][rustc] +# libcnb-package   [![Docs]][docs.rs] [![Latest Version]][crates.io] [![MSRV]][install-rust] A library for cross-compiling and packaging buildpacks written with [libcnb.rs](https://github.com/heroku/libcnb.rs). @@ -9,8 +7,8 @@ In most cases you should use [libcnb-cargo](https://crates.io/crates/libcnb-carg directly. [Docs]: https://img.shields.io/docsrs/libcnb-package -[docs.rs]: https://docs.rs/libcnb/*/libcnb-package/ +[docs.rs]: https://docs.rs/libcnb-package/latest/libcnb_package/ [Latest Version]: https://img.shields.io/crates/v/libcnb-package.svg [crates.io]: https://crates.io/crates/libcnb-package -[Rustc Version 1.58+]: https://img.shields.io/badge/rustc-1.58+-lightgray.svg -[rustc]: https://blog.rust-lang.org/2022/01/13/Rust-1.58.0.html +[MSRV]: https://img.shields.io/badge/MSRV-rustc_1.59+-lightgray.svg +[install-rust]: https://www.rust-lang.org/tools/install diff --git a/libcnb-proc-macros/Cargo.toml b/libcnb-proc-macros/Cargo.toml index 72bf6176..911ae9c7 100644 --- a/libcnb-proc-macros/Cargo.toml +++ b/libcnb-proc-macros/Cargo.toml @@ -7,8 +7,8 @@ license = "BSD-3-Clause" description = "Procedural macros used within libcnb.rs" repository = "https://github.com/heroku/libcnb.rs/tree/main/libcnb-proc-macros" documentation = "https://docs.rs/libcnb-proc-macros" -readme = "../README.md" -include = ["src/**/*", "../LICENSE", "../README.md"] +readme = "README.md" +include = ["src/**/*", "../LICENSE", "README.md"] [lib] proc-macro = true diff --git a/libcnb-proc-macros/README.md b/libcnb-proc-macros/README.md new file mode 100644 index 00000000..9b65f187 --- /dev/null +++ b/libcnb-proc-macros/README.md @@ -0,0 +1,13 @@ +# libcnb-proc-macros   [![Docs]][docs.rs] [![Latest Version]][crates.io] [![MSRV]][install-rust] + +Procedural macros used within the [libcnb.rs](https://github.com/heroku/libcnb.rs) framework. + +In most cases you should use the [libcnb](https://crates.io/crates/libcnb) crate rather than +depending on this crate directly. + +[Docs]: https://img.shields.io/docsrs/libcnb-proc-macros +[docs.rs]: https://docs.rs/libcnb-proc-macros/latest/libcnb_proc_macros/ +[Latest Version]: https://img.shields.io/crates/v/libcnb-proc-macros.svg +[crates.io]: https://crates.io/crates/libcnb-proc-macros +[MSRV]: https://img.shields.io/badge/MSRV-rustc_1.59+-lightgray.svg +[install-rust]: https://www.rust-lang.org/tools/install diff --git a/libcnb-test/README.md b/libcnb-test/README.md index 2714d5de..a752181a 100644 --- a/libcnb-test/README.md +++ b/libcnb-test/README.md @@ -1,4 +1,4 @@ -# libcnb-test +# libcnb-test   [![Docs]][docs.rs] [![Latest Version]][crates.io] [![MSRV]][install-rust] An experimental integration testing framework for Cloud Native Buildpacks written in Rust with libcnb.rs. @@ -55,3 +55,10 @@ fn call_test_fixture_service(addr: std::net::SocketAddr, payload: &str) -> Resul - Only local Docker daemons are fully supported. If using Circle CI you must use the [`machine` executor](https://circleci.com/docs/2.0/executor-types/#using-machine) rather than the [remote docker](https://circleci.com/docs/2.0/building-docker-images/) feature. + +[Docs]: https://img.shields.io/docsrs/libcnb-test +[docs.rs]: https://docs.rs/libcnb-test/latest/libcnb_test/ +[Latest Version]: https://img.shields.io/crates/v/libcnb-test.svg +[crates.io]: https://crates.io/crates/libcnb-test +[MSRV]: https://img.shields.io/badge/MSRV-rustc_1.59+-lightgray.svg +[install-rust]: https://www.rust-lang.org/tools/install From a18b507dd9255733ac0dda9f41b80875d99d81d4 Mon Sep 17 00:00:00 2001 From: Ed Morley <501702+edmorley@users.noreply.github.com> Date: Thu, 7 Jul 2022 10:47:11 +0100 Subject: [PATCH 2/2] Couple more tweaks --- README.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 142507d9..69d0c513 100644 --- a/README.md +++ b/README.md @@ -9,7 +9,9 @@ [MSRV]: https://img.shields.io/badge/MSRV-rustc_1.59+-lightgray.svg [install-rust]: https://www.rust-lang.org/tools/install -`libcnb.rs` is a framework for writing [Cloud Native Buildpacks](https://buildpacks.io) in Rust. It is an opinionated implementation adding language constructs and convenience methods for working with the spec. It values strong adherence to the spec and data formats. +`libcnb.rs` is a framework for writing [Cloud Native Buildpacks](https://buildpacks.io) in Rust. +It is an opinionated implementation adding language constructs and convenience methods for working +with the spec. It values strong adherence to the spec and data formats. It currently targets version `0.6` of the CNB spec. @@ -25,7 +27,8 @@ be carried out once and don't need to be repeated for each buildpack you will wr #### libcnb Cargo Command -Start by installing the libcnb Cargo command which we will later use to package our buildpack: +Start by installing [libcnb-cargo](https://crates.io/crates/libcnb-cargo), which provides the `libcnb` Cargo command +that we will use later to package our buildpack: ```shell $ cargo install libcnb-cargo