usability enhancement: fail with a polite message when invoking in src

[codebot]

Sometimes, due to rapid-fire directory navigation and having many unrelated items bouncing around in one's head, it's possible to invoke colcon build in the src directory of a workspace, rather than in the "root" workspace directory. This will create a new set of build and install directories as subdirectories of src but otherwise "seems to work" at least sometimes. This can lead to great confusion when other terminals have sourced the "original" install directory.

I can't quite think of a case where it's useful to run colcon build in a directory named src. I suggest that colcon exits with a kind and polite message like "Because I love you, I won't do what you just asked me to do. Please go up a directory and try again. Have a nice day."

I'm happy to create this PR, but wanted to ask first before proceeding.

[dirk-thomas]

Imo it isn't sufficient to check if the cwd is named src to abort the build. While it might be uncommon I don't see why the tool should be enforcing this.

I think what you want instead is the feature described in #139. Assuming that is the case I will go ahead and close this as a duplicate.

[codebot]

#139 indeed would address this issue, but it's a superset of what is needed to solve this problem (and #366, and surely we're not the only two people to experience this first-hand and second-hand). #139 would "do the right thing" no matter where colcon is invoked. This suggestion is (I think) much simpler: prevent colcon from "doing the wrong thing" and exiting with a simple message which prompts the user to change directories (manually) and invoke colcon again. I think this would be simple to implement.

I agree checking if cwd is src is probably not the right thing to do, since there are many "wrong" directories to invoke colcon, not just src. Thank you for that point.

What if, instead, the tool checks to see that cwd has a subdirectory named src, and stops if it does not? In my experience using and watching people use colcon, that would solve the vast majority of wrong-directory invocations. I'm happy to make an initial PR candidate for discussion, if we're on the same page.

[dirk-thomas]

What if, instead, the tool checks to see that cwd has a subdirectory named src, and stops if it does not?

That condition on its own is unfortunately also not sufficient to stop the invocation. While having a src directory is the common pattern for workspaces in ROS there are many different ways colcon can be used - just as one example it could be involved without any single directory containing the package sources.

So I don't think colcon should limit the possible use cases for the sake of making something easier / more convenient for ROS alone.

#139 is imo the right way to handle this without compromising other use cases. For this case to be satisfied it isn't even necessary to implement the referenced ticket in full scope since it doesn't need to actually perform the invocation but only needs to detect the case and tell the user where to invoje the command instead. That subset should be much easier to implement since it mainly requires being able to identify a previously built workspace.