Add Buildroot and mix.exs config to generated README

Author: fhunleth

generate_toolchains.exs

@@ -61,6 +61,7 @@ defmodule ToolchainGenerator do
     app_name = "nerves_toolchain_#{target_tuple}"
     target_dir = Path.expand(app_name)
     config_dir = "configs/#{app_name}"
+    versions = Map.get(version_metadata, app_name, [])
 
     IO.puts("Generating #{target_dir}...")
 
@@ -73,8 +74,9 @@ defmodule ToolchainGenerator do
     # Prepare bindings for EEx templates
     module_name = target_tuple_to_module_name(target_tuple)
     target_display = target_tuple |> to_string() |> String.replace("_", "-")
-    included_components = build_included_components(Map.get(version_metadata, app_name, []))
+    included_components = build_included_components(versions)
     package_licenses_list = format_string_list(build_package_licenses(included_components))
+    external_toolchain_settings = build_external_toolchain_settings!(versions)
 
     bindings = [
       module_name: module_name,
@@ -83,7 +85,9 @@ defmodule ToolchainGenerator do
       target_display: target_display,
       ctng_tag: Map.fetch!(toolchain_config, :ctng_tag),
       included_components: included_components,
-      package_licenses_list: package_licenses_list
+      package_licenses_list: package_licenses_list,
+      linux_headers_series: external_toolchain_settings.linux_headers_series,
+      libc_type: external_toolchain_settings.libc_type
     ]
 
     template_dir = Path.expand("template")
@@ -143,6 +147,34 @@ defmodule ToolchainGenerator do
     end)
   end
 
+  defp build_external_toolchain_settings!(versions) do
+    versions_by_component = Map.new(versions)
+
+    %{
+      linux_headers_series: linux_headers_series!(versions_by_component),
+      libc_type: libc_type!(versions_by_component)
+    }
+  end
+
+  defp linux_headers_series!(versions_by_component) do
+    versions_by_component
+    |> Map.fetch!("Linux headers")
+    |> String.split(".")
+    |> Enum.take(2)
+    |> case do
+      [major, minor] -> "#{major}_#{minor}"
+      _ -> raise "expected Linux headers version to include major and minor numbers"
+    end
+  end
+
+  defp libc_type!(versions_by_component) do
+    cond do
+      Map.has_key?(versions_by_component, "glibc") -> "GLIBC"
+      Map.has_key?(versions_by_component, "musl") -> "MUSL"
+      true -> raise "expected glibc or musl in toolchain version metadata"
+    end
+  end
+
   defp build_package_licenses(included_components) do
     included_components
     |> Enum.map(&elem(&1, 2))

template/README.md.eex

@@ -13,6 +13,34 @@ cross-compilers can be referenced in `mix`. See
 [nerves-toolchain](https://github.com/nerves-project/nerves-toolchain) for
 the scripts used to generate the actual cross-compiler.
 
+## Using this toolchain in a Nerves system
+
+Add this toolchain to your Nerves system project's `deps` in `mix.exs`:
+
+```elixir
+{:<%= @app_name %>, "~> <toolchain version>", runtime: false}
+```
+
+Then update `nerves_defconfig` to use the release artifact for this toolchain.
+The easiest way is to copy the external toolchain settings from this package's
+`defconfig`. In addition to pointing `BR2_TOOLCHAIN_EXTERNAL_URL` at the
+release archive for your host and setting the custom prefix, make sure the
+kernel headers, libc, and language/runtime options match:
+
+```make
+BR2_TOOLCHAIN_EXTERNAL=y
+BR2_TOOLCHAIN_EXTERNAL_CUSTOM=y
+BR2_TOOLCHAIN_EXTERNAL_DOWNLOAD=y
+BR2_TOOLCHAIN_EXTERNAL_URL="https://github.com/nerves-project/toolchains/releases/download/<tag>/<artifact>"
+BR2_TOOLCHAIN_EXTERNAL_CUSTOM_PREFIX="<%= @target_display %>"
+BR2_TOOLCHAIN_EXTERNAL_HEADERS_<%= @linux_headers_series %>=y
+BR2_TOOLCHAIN_EXTERNAL_CUSTOM_<%= @libc_type %>=y
+# BR2_TOOLCHAIN_EXTERNAL_INET_RPC is not set
+BR2_TOOLCHAIN_EXTERNAL_CXX=y
+BR2_TOOLCHAIN_EXTERNAL_FORTRAN=y
+BR2_TOOLCHAIN_EXTERNAL_OPENMP=y
+```
+
 <%= if @included_components != [] do %>
 ## Included tool versions and licenses