Skip to content

Commit

Permalink
Improve the documentation for ctx.actions.symlink.
Browse files Browse the repository at this point in the history
This API does two different things and users occasionally get confused by it (see e.g. #16070). In particular, it is crucial to understand whether Bazel tracks the symlink on its own or the contents of its target.

PiperOrigin-RevId: 483604065
Change-Id: Iab14c264eb320cd324b64b3af2a400df948dbf3c
  • Loading branch information
tjgq authored and copybara-github committed Oct 25, 2022
1 parent 1a38552 commit 5cea7dd
Showing 1 changed file with 15 additions and 13 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -163,19 +163,21 @@ public interface StarlarkActionFactoryApi extends StarlarkValue {
@StarlarkMethod(
name = "symlink",
doc =
"Creates an action that writes a symlink in the file system."
+ "<p>This function must be called with exactly one of <code>target_file</code> or "
+ "<code>target_path</code> specified.</p>"
+ "<p>If <code>target_file</code> is used, then <code>output</code> must be declared "
+ "by <a href=\"#declare_file\"><code>declare_file()</code></a> or "
+ "<a href=\"#declare_directory\"><code>declare_directory()</code></a> and match the "
+ "type of <code>target_file</code>. In this case, <code>output</code> will be a "
+ "symlink whose contents are the path of <code>target_file</code>.</p>"
+ "<p>Otherwise, if <code>target_path</code> is used, then <code>output</code> must "
+ "be declared with "
+ "<a href=\"#declare_symlink\"><code>declare_symlink()</code></a>). In this case, "
+ "<code>output</code> will be a symlink whose contents are <code>target_path</code>."
+ "This can be used to create a dangling symlink.</p>",
"Creates an action that writes a symlink in the file system.<p>This function must be"
+ " called with exactly one of <code>target_file</code> or <code>target_path</code>"
+ " specified.</p><p>When you use <code>target_file</code>, declare"
+ " <code>output</code> with <a"
+ " href=\"#declare_file\"><code>declare_file()</code></a> or <a"
+ " href=\"#declare_directory\"><code>declare_directory()</code></a> and match the"
+ " type of <code>target_file</code>. This makes the symlink point to"
+ " <code>target_file</code>. Bazel invalidates the output of this action whenever"
+ " the target of the symlink or its contents change.</p><p>Otherwise, when you use"
+ " <code>target_path</code>, declare <code>output</code> with <a"
+ " href=\"#declare_symlink\"><code>declare_symlink()</code></a>). In this case, the"
+ " symlink points to <code>target_path</code>. Bazel never resolves the symlink"
+ " and the output of this action is invalidated only when the text contents of the"
+ " symlink (that is, the value of <code>readlink()</code>) changes. In particular,"
+ " this can be used to create a dangling symlink.</p>",
parameters = {
@Param(
name = "output",
Expand Down

0 comments on commit 5cea7dd

Please sign in to comment.