purpose of box:::path_tests$rstudio_path, and behavior in RStudio/Posit

[tyner]

Error description

Say I have an R script

setwd("/home/btyner/branches/r_main")
f <- box::file()
message("file is ", f)

If I run the script by manually source()ing it, f is "/home/btyner/branches/r_main". However, if I instead click the "Source" button from RStudio Desktop or Posit Workbench, f is a different directory. It seems the different behavior is due to box:::path_tests$rstudio_path (equivalently box:::rstudio_path) which makes use of the RStudio API and alters its behavior accordingly.

The difference in behavior is also observed for box::use(). In other words, this pattern

setwd("/home/btyner/branches/r_main")
box::use(./Foo/Bar[...])

will behave differently depending on the method the user chooses for sourcing.

I imagine many users believe that clicking the "Source" button is equivalent to manually running source(), since that is what is echoed on the screen upon clicking the button.

In any case, I assume the behavior observed is actually as designed, and that this is not a bug, but I am wondering what is the benefit of this? I did see some documentation under help(topic = "path", package = "box") but it doesn't really make clear that the "Source" button is special in this regard.

Thank you for considering.

R version

platform       x86_64-w64-mingw32               
arch           x86_64                           
os             mingw32                          
crt            ucrt                             
system         x86_64, mingw32                  
status                                          
major          4                                
minor          5.3                              
year           2026                             
month          03                               
day            11                               
svn rev        89597                            
language       R                                
version.string R version 4.5.3 (2026-03-11 ucrt)
nickname       Reassured Reassurer

‘box’ version

1.2.1

[klmr]

tl;dr: when box::use() is run from inside a file, the import location is resolved relative to the containing file, because this is the most useful behaviour. When box::use() is run outside a file (e.g. from the R console), the notion of “relative to the containing file” makes no sense (there’s no file!), and import paths are resolved relative to the current working directory. — And equivalently for box::file().

---

I imagine many users believe that clicking the "Source" button is equivalent to manually running source(), since that is what is echoed on the screen upon clicking the button.

You have a point there. On the other hand, users generally¹ expect that box::use() (and, by implication, box::file()) resolve the path relative to the current file, not to whatever the current working directory happens to be, which is in general completely unrelated to the location of the code being run. This is particularly true with more complex project structures (where not all source files are in a single, flat folder), which is precisely the use-case that ‘box’ aims to enable.

Therefore, that’s how ‘box’ resolves paths when users press the “Source” button in RStudio.

¹ not universally, but I’d claim that this is the most common expectation, and jibes with what users are used to from other, non-R systems

By contrast, source() isn’t always tied to a calling file. For instance, users could run source() from an active R terminal, with no file in sight. In this case, ‘box’ can’t infer a suitable origin location (= “what path am I called from?”), so it reverts to the current working directory.

In particular, if you run source("myfile.r") from the R console inside RStudio, the RStudio API will return that there’s no currently-active file (and IMHO this is the correct behaviour! Positron unhelpfully chose a different behaviour). So even if ‘box’ wanted to provide the same behaviour for calling source() as for pressing the “Source” button it couldn’t, due to how RStudio’s API handles the concept of “active document”.

---

The fact that RStudio wrongly pretends that clicking “Source” is equivalent to calling source() is pretty misleading and, arguably, a bug in RStudio: the behaviour is not the same as far as RStudio itself is concerned (as evidenced by the different behaviour of its API in both cases, unrelated to ‘box’!).

[tyner]

Thank you for the explanation! I would humbly suggest this portion of the documentation be updated to reflect that nuance, in particular the bolded portion,

The current directory is context-dependent: inside a module, the directory corresponds to the module’s directory. Inside an R code file invoked from the command line, it corresponds to the directory containing that file. If the code is running inside a Shiny application or a knitr document, the directory of the execution is used. Otherwise (e.g. in an interactive R session), the current working directory as given by getwd() is used.

In any case, I guess the way to go is to get into the habit of setting

options(box.path = "/home/btyner/branches/r_main")

rather than setting the working directory.

[klmr]

Hi @tyner, I have to admit that I was tired/distracted yesterday when writing the message, and I realised later that, while the technical explanation is correct, it doesn’t really apply to explain why source("some/file.r") doesn’t have the same effect (as far as ‘box’ is concerned) as pressing the “Source” button. — After all, when running source() we do have a file from inside which box::use() is run, so it should be possible to suss out the location. There are multiple reasons why ‘box’ doesn’t support this:

1. Foremost, ‘box’ obviously aims to replace source(), so instead of source("….r") you could use box::use(…). It hadn’t occurred to me, until you pointed it out, that RStudio’s “Source” is misleading users by pretending to execute source().
2. Figuring out the file path of a source() call from inside that call isn’t hard, but it requires looking at undocumented implementation details, so it isn’t future-proof: an R update might break the code at any moment.
3. Solving (2) is slightly inefficient, and finding the correct path (via the box:::path_tests) already needs to iterate through several candidates, and this needs to happen on every box::use() invocation, so it’s somewhat important to keep this efficient.

None of these factors are absolute blockers, but at this point changing the behaviour of ‘box’ inside source() would be a breaking change, so it won’t happen in version 2.x. I might consider it for version 3.

That said, I’ll make the documentation clearer as you suggested.