{"id":24690361,"url":"https://github.com/kentaro/mix_tasks_upload_hotswap","last_synced_at":"2025-10-12T11:50:06.355Z","repository":{"id":57527990,"uuid":"314298581","full_name":"kentaro/mix_tasks_upload_hotswap","owner":"kentaro","description":"Deploy local code changes to the remote node(s) in a hot-code-swapping manner","archived":false,"fork":false,"pushed_at":"2024-12-22T00:59:11.000Z","size":36,"stargazers_count":37,"open_issues_count":2,"forks_count":2,"subscribers_count":4,"default_branch":"main","last_synced_at":"2025-04-09T18:16:29.272Z","etag":null,"topics":["elixir","nerves"],"latest_commit_sha":null,"homepage":"https://github.com/kentaro/mix_tasks_upload_hotswap","language":"Elixir","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kentaro.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-11-19T16:02:43.000Z","updated_at":"2024-12-22T00:59:15.000Z","dependencies_parsed_at":"2022-09-03T19:40:50.786Z","dependency_job_id":null,"html_url":"https://github.com/kentaro/mix_tasks_upload_hotswap","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kentaro%2Fmix_tasks_upload_hotswap","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kentaro%2Fmix_tasks_upload_hotswap/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kentaro%2Fmix_tasks_upload_hotswap/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kentaro%2Fmix_tasks_upload_hotswap/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kentaro","download_url":"https://codeload.github.com/kentaro/mix_tasks_upload_hotswap/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248085323,"owners_count":21045139,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["elixir","nerves"],"created_at":"2025-01-26T18:20:04.705Z","updated_at":"2025-10-12T11:50:01.330Z","avatar_url":"https://github.com/kentaro.png","language":"Elixir","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mix.Tasks.Upload.Hotswap [![hex.pm version](https://img.shields.io/hexpm/v/mix_tasks_upload_hotswap.svg)](https://hex.pm/packages/mix_tasks_upload_hotswap)\n\n\nThis package provides a mix task named `mix upload.hotswap` to deploy local code changes to remote node(s) and to apply them without rebooting whole the application (the so-called `hot code swapping`).\n\nIt could be convenient when you code for IoT devices backed by [Nerves](https://www.nerves-project.org/) because it's much faster than `mix firmware \u0026\u0026 mix upload`. Although you eventually need to update the firmware if you want to persist the changes onto devices, this task could be your help in development phase because it allows you to quickly confirm if your changes work fine on the devices without waiting long time.\n\n## Installation\n\nAdd `mix_tasks_upload_hotswap` to your list of dependencies in `mix.exs`:\n\n```elixir\ndef deps do\n  [\n    {:mix_tasks_upload_hotswap, \"~\u003e 0.1.0\", only: :dev}\n  ]\nend\n```\n\n## Prerequisites\n\nTo use this package, you need to meet the requirements below:\n\n1. Add configurations for `mix upload.hotswap`\n2. Start node(s) on your device(s) through which your code changes are deployed\n\n### 1. Add configurations for `mix upload.hotswap`\n\nThe task `mix upload.hotswap` depends on the settings below are available:\n\n```elixir\nconfig :mix_tasks_upload_hotswap,\n  app_name: :example,\n  nodes: [:\"example@nerves.local\"],\n  cookie: :\"secret token shared between nodes\"\n```\n\nAll the pairs above are required to be set.\n\nSee [example/config/config.exs](https://github.com/kentaro/mix_tasks_upload_hotswap/blob/main/example/config/config.exs) for working example.\n\n### 2. Start node(s) on your device(s) through which your code changes are deployed\n\nStart a node which has the name and cookie set in the configuration above. The code should be like below:\n\n```elixir\n# Start a node through which local code changes are deployed\n# only when the device is running in the develop environment\nif Application.get_env(:example, :env) == :dev do\n  System.cmd(\"epmd\", [\"-daemon\"])\n  Node.start(:\"example@nerves.local\")\n  Node.set_cookie(Application.get_env(:mix_tasks_upload_hotswap, :cookie))\nend\n```\n\nNotice that the node starts only when the `:env` of the application is set to `:dev`. Below is an example to configure the environment value in `config.exs`:\n\n```elixir\nconfig :example, env: Mix.env()\n```\n\nSee [example/lib/example/application.ex](https://github.com/kentaro/mix_tasks_upload_hotswap/blob/main/example/lib/example/application.ex) and [example/config/config.exs](https://github.com/kentaro/mix_tasks_upload_hotswap/blob/main/example/config/config.exs) for working example.\n\n## Usage\n\n### Mix Task\n\nMake some changes into your code and just execute the mix task as below:\n\n```sh\n$ mix upload.hotswap\n```\n\n### Illustration by `Example` App\n\nImagine there is an [Example](https://github.com/kentaro/mix_tasks_upload_hotswap/tree/main/example) application which has `hello` method as below:\n\n```elixir\ndef hello do\n  :world\nend\n```\n\nYou can confirm the method invoked on your device:\n\n```sh\n$ ssh nerves.local\n(snip)\n\niex(example@nerves.local)1\u003e Example.hello\n:world\n```\n\nSuppose you made some changes like below:\n\n```diff\ndiff --git a/example/lib/example.ex b/example/lib/example.ex\nindex ca49896..81c696a 100644\n--- a/example/lib/example.ex\n+++ b/example/lib/example.ex\n@@ -13,6 +13,6 @@ defmodule Example do\n\n   \"\"\"\n   def hello do\n-    :world\n+    :\"new world\"\n   end\n end\n```\n\nYou can deploy the changes to the device as below:\n\n```sh\n$ mix upload.hotswap\n==\u003e nerves\n==\u003e example\n\nNerves environment\n  MIX_TARGET:   rpi3\n  MIX_ENV:      dev\n\nCompiling 2 files (.ex)\nGenerated example app\nSuccessfully connected to example@nerves.local\nSuccessfully deployed Elixir.Example to example@nerves.local\nSuccessfully deployed Elixir.Example.Application to example@nerves.local\n```\n\nNow you can see the changes applied into the code on the device:\n\n```sh\n$ ssh nerves.local\n(snip)\n\niex(example@nerves.local)1\u003e Example.hello\n:\"new world\"\n```\n\nIt's much faster than `mix firmware \u0026\u0026 mix upload`.\n\n### Options\n\n#### --node\n\nYou can specify the node(s) in the cluster as below:\n\n```sh\n$ mix upload.hotswap --node example@nerves.local\n```\n\nThis `--node` option can be used multiple times.\n\n#### --module\n\nYou can specify the module(s) as below:\n\n```sh\n$ mix upload.hotswap --module YourGoodApp\n```\n\nThis `--module` option\n\n  - can be used multiple times.\n  - searches for all modules that start with the specified module name.\n\n## Acknowledgement\n\n[Using Erlang Distribution to test hardware - Embedded Elixir](https://embedded-elixir.com/post/2018-12-10-using-distribution-to-test-hardware/) inspired me how to implement this package.\n\n## Author\n\n[Kentaro Kuribayashi](https://kentarokuribayashi.com/)\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkentaro%2Fmix_tasks_upload_hotswap","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkentaro%2Fmix_tasks_upload_hotswap","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkentaro%2Fmix_tasks_upload_hotswap/lists"}