diff --git a/README.md b/README.md index 9743cc2..61723a9 100644 --- a/README.md +++ b/README.md @@ -22,23 +22,116 @@ end ## Usage +### 1. Initialization + ``` $ mix blend.init ``` -Edit and set your blends in auto-generated `blend.exs` file. +### 2. Define your blends + +Edit and set your blends in the auto-generated `blend.exs` file. + + +### 3. Resolve blends and generate lockfiles ``` $ mix blend.get ``` -to generate lockfiles with variations of your dependencies. +to resolve your blends and generate new lockfiles with variations of your dependencies under the new `/blend` folder. + +### 4. Ignore blend build artifacts + +Add + +``` +# .gitignore + +/blend/_build +/blend/deps +``` + +to your `.gitignore` file. + +before comitting your changes. + + +### 5. Running in the context of a blend lockfile + +#### Option A. Overriding your `mix.lock`. + +If you just need a CI job step to run against a blend lockfile, it might be enough to just: + +``` +$ mv blend/.mix.lock mix.lock +``` + +as a CI step before `mix deps.get`. + +#### Option B. `BLEND` env var configuration + +A more permanent configuration for running mix tasks in the context of a blend lockfile with a simple env var +can be acomplished by customizing your `mix.exs` a bit, with the following steps. + +##### 1. Create a new file `blend/premix.exs` with the following contents: + +```elixir +# blend/premix.exs + +maybe_put_env = fn varname, value -> + System.put_env(varname, System.get_env(varname, value)) +end + +blend = System.get_env("BLEND") + +if blend && String.length(blend) > 0 do + maybe_put_env.("MIX_LOCKFILE", "blend/#{blend}.mix.lock") + maybe_put_env.("MIX_DEPS_PATH", "blend/deps/#{blend}") + maybe_put_env.("MIX_BUILD_ROOT", "blend/_build/#{blend}") +end +``` + +##### 2. Add `Code.compile_file("blend/premix.exs")` statement to the top of your `mix.exs`. + +##### 3. Conditionally set the `lockfile` option in your `mix.exs`'s `def project`. + +Something like this would be enough: + +```elixir +# In mix.exs + + def project do + [ + ... + ] + |> Keyword.merge(maybe_lockfile_option()) + end + + defp maybe_lockfile_option do + case System.get_env("MIX_LOCKFILE") do + nil -> [] + "" -> [] + lockfile -> [lockfile: lockfile] + end + end +``` + +##### 4. Enjoy -See your new extra lockfiles listed under `/blend` folder. +Now you can run any task, e.g. run your tests, against different lockfiles locally by just executing: -Edit and set custom `lockfile`, `deps_path`, and `build_path` options in your `mix.exs` project, +``` +$ BLEND= mix test +``` + +### 6. Updating blend lockfiles + +``` +$ mix blend.update --all +``` -Also you probably want to ignore `/blend/_build` and `/blend/deps` in your `.gitignore`. +whenever you want to update all your blend lockfiles to latest possible versions. ## License