From f5ac1a3f46ef84fed776ce85e225c03309ad34bb Mon Sep 17 00:00:00 2001 From: David Biancolin Date: Mon, 6 Dec 2021 16:54:24 -0800 Subject: [PATCH] [docs] Explain how to modify published dependencies --- .../Managing-Published-Scala-Dependencies.rst | 54 +++++++++++++++++++ docs/Advanced-Concepts/index.rst | 1 + 2 files changed, 55 insertions(+) create mode 100644 docs/Advanced-Concepts/Managing-Published-Scala-Dependencies.rst diff --git a/docs/Advanced-Concepts/Managing-Published-Scala-Dependencies.rst b/docs/Advanced-Concepts/Managing-Published-Scala-Dependencies.rst new file mode 100644 index 0000000000..4e3fcd0d00 --- /dev/null +++ b/docs/Advanced-Concepts/Managing-Published-Scala-Dependencies.rst @@ -0,0 +1,54 @@ +Managing Published Scala Dependencies +===================================== + +In preparation for Chisel 3.5, in Chipyard 1.5 Chisel, FIRRTL, the FIRRTL +interpreter, and Treadle, were transitioned from being built-from-source to +managed as published dependencies. Their submodules have been removed. +Switching between published versions can be achieved by changing the versions +specified in Chipyard's build.sbt. + +Lists of available artifacts can be using search.maven.org or mvnrepository.org: + +- `Chisel3 `_ +- `FIRRTL `_ +- `FIRRTL Interpreter `_ +- `Treadle `_ + + +Publishing Local Changes +------------------------- + +Under the new system, the simplest means to make custom source modifications to the packages +above is to run ``sbt +publishLocal`` from within a locally modified clone of each +of their respective repositories. This will post your custom variant +to your local ivy2 repository, which can generally be found at ~/.ivy2. See the `SBT +documentation `_ +for more detail. + +In practice, this will require the following steps: + +#. Check out and modify the desired projects. +#. Take note of, or modify, the versions of each projects (in + their build.sbt). If you're cloning from master generally + these will have default versions of ``1.X-SNAPSHOT``, where ``X`` is + not-yet-released next major version. You can modify the version string, to say ``1.X-``, to uniquely identify your + change. +#. Call ``sbt +publishLocal`` in each subproject. You may need to rebuild other + published dependencies. SBT will be clear about what it is publishing and + where it is putting it. The ``+`` is generally necessary and ensures that + all cross versions of the package are published. +#. Update the Chisel or FIRRTL version in Chipyard's build.sbt to match the + versions of your locally published packages. +#. Use Chipyard as you would normally. Now when you call out to make in + Chipyard you should see SBT resolving dependencies to the locally + published instances in your local ivy2 repository. +#. When you're finished, consider removing your locally published packages (by + removing the appropriate directory in your ivy2 repository) to prevent + accidentally reusing them in the future. + +A final word of caution: packages you publish to your local ivy repository will +be visible to other projects you may be building on your system. For example, +if you locally publish Chisel 3.5.0, other projects that depend on Chisel 3.5.0 +will preferentially use the locally published variant over the version +available on Maven (the "real" 3.5.0). Take care to note versions you are +publishing and remove locally published versions once you are done with them. diff --git a/docs/Advanced-Concepts/index.rst b/docs/Advanced-Concepts/index.rst index b294d11b52..d4092c6788 100644 --- a/docs/Advanced-Concepts/index.rst +++ b/docs/Advanced-Concepts/index.rst @@ -15,4 +15,5 @@ They expect you to know about Chisel, Parameters, configs, etc. Resources CDEs Harness-Clocks + Managing-Published-Scala-Dependencies