feat: add build vars. for rockspecs with the dir. of its deps.

Rockspecs can access the directory of its dependencies using variables
in the format 'foo_ROCKDIR' where 'foo' is the name of a dependency.
This is used to be able to access files of the rock like 'conf', 'docs'
and more.

4 files changed, 69 insertions, 6 deletions

diff --git a/docs/creating_a_rock.md b/docs/creating_a_rock.md
index 1d42b07f..a5441ea4 100644
--- a/docs/creating_a_rock.md
+++ b/docs/creating_a_rock.md
@@ -148,6 +148,14 @@ and `5.3`, but not yet-to-be-released `5.4`. There are a few other operators
 for specifying version constraints, see
 [Rockspec format](rockspec_format.md#dependency-information).
 
+Rockspecs from [`rockspec_format = "3.1"`](rockspec_format.md#package-metadata)),
+have access to special variables with the path of the installed rocks of its
+dependencies. See the [section below](#including-documentation-and-other-files)
+for information on how rocks can include files in their installation. Each
+variable is the name of the dependency followed by the suffix `_ROCKDIR`. For
+the example above, variable `LUAKNIFE_ROCKDIR` will be provided with the path of
+the installed rock.
+
 #### C modules linking to external libraries
 
 *If your code does not use third-party libraries, you may skip this subsection.*
diff --git a/spec/build_spec.lua b/spec/build_spec.lua
index ad6f4d42..2e139a41 100644
--- a/spec/build_spec.lua
+++ b/spec/build_spec.lua
@@ -417,6 +417,55 @@ describe("LuaRocks build #integration", function()
             assert.is.truthy(run.luarocks("show uses_luaversion_variable"))
          end, finally)
       end)
+
+
+      it("dependency directory is not provided for old format", function()
+         test_env.run_in_tmp(function(tmpdir)
+            local rocks_tree = run.luarocks("config variables.ROCKS_TREE")
+            local rocks_path = table.concat({rocks_tree, "a_rock", "1.0-1"}, package.config:sub(1, 1))
+            write_file("verify_argument.lua", string.format("assert(arg[1] == %q)", rocks_path))
+            write_file("uses_rockdir_variable-3.1-11.rockspec", [[
+               package = "uses_rockdir_variable"
+               version = "3.1-11"
+               source = {
+                  url = "file://]] .. tmpdir:gsub("\\", "/") .. [[/verify_argument.lua"
+               }
+               dependencies = {
+                  "a_rock 1.0"
+               }
+               build = {
+                  type = "command",
+                  build_command = "$(LUA) verify_argument.lua $(A_ROCK_ROCKDIR)",
+               }
+            ]])
+            assert.is_false(run.luarocks_bool("build uses_rockdir_variable-3.1-11.rockspec"))
+         end, finally)
+      end)
+
+      it("dependency directory is provided as variable", function()
+         test_env.run_in_tmp(function(tmpdir)
+            local rocks_tree = run.luarocks("config variables.ROCKS_TREE")
+            local rocks_path = table.concat({rocks_tree, "a_rock", "1.0-1"}, package.config:sub(1, 1))
+            write_file("verify_argument.lua", string.format("assert(arg[1] == %q)", rocks_path))
+            write_file("uses_rockdir_variable-3.1-11.rockspec", [[
+               rockspec_format = "3.1"
+               package = "uses_rockdir_variable"
+               version = "3.1-11"
+               source = {
+                  url = "file://]] .. tmpdir:gsub("\\", "/") .. [[/verify_argument.lua"
+               }
+               dependencies = {
+                  "a_rock 1.0"
+               }
+               build = {
+                  type = "command",
+                  build_command = "$(LUA) verify_argument.lua $(A_ROCK_ROCKDIR)",
+               }
+            ]])
+            assert.is_truthy(run.luarocks_bool("build uses_rockdir_variable-3.1-11.rockspec"))
+            assert.is.truthy(run.luarocks("show uses_rockdir_variable"))
+         end, finally)
+      end)
    end)
 
    describe("#mock external dependencies", function()
diff --git a/src/luarocks/deps.lua b/src/luarocks/deps.lua
index 19cf6936..5802601e 100644
--- a/src/luarocks/deps.lua
+++ b/src/luarocks/deps.lua
@@ -329,9 +329,12 @@ function deps.fulfill_dependencies(rockspec, depskey, deps_mode, verify, deplock
       util.printout(("%s %s depends on %s (%s)"):format(
       name, version, tostring(depq), (rock_status(depq, get_versions))))
 
-      local okfulfill, found_or_err, _ = deps.fulfill_dependency(depq, deps_mode, rocks_provided, verify, depskey)
+      local okfulfill, version_or_err, tree = deps.fulfill_dependency(depq, deps_mode, rocks_provided, verify, depskey)
       if okfulfill then
-         deplocks.add(depskey, depq.name, found_or_err)
+         deplocks.add(depskey, depq.name, version_or_err)
+         if tree and rockspec:format_is_at_least("3.1") then
+            rockspec.variables[depq.name:upper() .. "_ROCKDIR"] = path.install_dir(depq.name, version_or_err, tree)
+         end
       else
          if depq.constraints and depq.constraints[1] and depq.constraints[1].no_upgrade then
             util.printerr("This version of " .. name .. " is designed for use with")
@@ -341,7 +344,7 @@ function deps.fulfill_dependencies(rockspec, depskey, deps_mode, verify, deplock
             util.printerr("or look for a suitable version of " .. name .. " with")
             util.printerr("   luarocks search " .. name)
          end
-         return nil, found_or_err
+         return nil, version_or_err
       end
    end
 
diff --git a/src/luarocks/deps.tl b/src/luarocks/deps.tl
index f6a6642f..d127288e 100644
--- a/src/luarocks/deps.tl
+++ b/src/luarocks/deps.tl
@@ -329,9 +329,12 @@ function deps.fulfill_dependencies(rockspec: Rockspec, depskey: DepsKey, deps_mo
       util.printout(("%s %s depends on %s (%s)"):format(
          name, version, tostring(depq), (rock_status(depq, get_versions))))
 
-      local okfulfill, found_or_err, _ = deps.fulfill_dependency(depq, deps_mode, rocks_provided, verify, depskey)
+      local okfulfill, version_or_err, tree = deps.fulfill_dependency(depq, deps_mode, rocks_provided, verify, depskey)
       if okfulfill then
-         deplocks.add(depskey, depq.name, found_or_err)
+         deplocks.add(depskey, depq.name, version_or_err)
+         if tree and rockspec:format_is_at_least("3.1") then
+            rockspec.variables[depq.name:upper() .. "_ROCKDIR"] = path.install_dir(depq.name, version_or_err, tree)
+         end
       else
          if depq.constraints and depq.constraints[1] and depq.constraints[1].no_upgrade then
             util.printerr("This version of "..name.." is designed for use with")
@@ -341,7 +344,7 @@ function deps.fulfill_dependencies(rockspec: Rockspec, depskey: DepsKey, deps_mo
             util.printerr("or look for a suitable version of "..name.." with")
             util.printerr("   luarocks search "..name)
          end
-         return nil, found_or_err
+         return nil, version_or_err
       end
    end