small update to docs for testing/building section #647
Conversation
a bit more docs on how to run tests and compile code faster
| @@ -75,6 +75,11 @@ Use the build scripts provided in the `ci/` directory to build tests for each co | |||
| ```bash | |||
| ./ci/build_cub.sh -cxx g++ -std 14 -arch "70;75;80-virtual" | |||
| ``` | |||
| Once you have run the script, and your configuration is properly set up, you can simply use `CMake` to build your targets which will be much faster than the CI scripts when checking to see if your code compiles. For example, to build `CUB` locally with C++ 17, you can run the following command. | |||
There was a problem hiding this comment.
question: What makes using the preset faster than the build script?
There was a problem hiding this comment.
I haven't done a deep enough dive on what the scripts are doing internally so I can't comment on the difference, but I've noticed empirically that it is much slower than just directly using the preset.
The feedback loop was really slow for me personally. If I made a small syntactical error in writing my code, it would take 2-3 minutes from running the build scripts before I got to see the error. That compounds really hard, where as running the preset build directly the feedback is nearly instantaneous.
There was a problem hiding this comment.
take 2-3 minutes from running the build scripts
That compounds really hard, where as running the preset build directly the feedback is nearly instantaneous.
That's good to know, thanks for raising this. I completely agree with not wanting to use the scripts if this is the experience you're having!
This is definitely not the behavior I would expect, so we'll need to investigate why this is happening for you.
There was a problem hiding this comment.
comment/question: I'm biased, but I'd hoped to steer most people towards using the build scripts in their normal workflow because there are things we can do in the scripts that we can't do in the presets.
Using the presets directly is totally fine and we should document it, but I'm curious to hear more from your perspective what makes those more appealing/accessible than using the scripts.
Some concrete questions, comments:
- Would the scripts seem less intimidating if they weren't in the
ci/directory and instead were just in the rootcccl/directory? - We haven't updated the documentation yet, but we recently made changes where the build/test scripts don't require any arguments by default anymore. There are sane defaults for the archs/std and the host/cuda compiler are set based on the devcontainer environment. So you can just run
build_thrust.shand it'll just work. Would that help make them more accessible? - I suspect [FEA]: Ability to add compiler flags to CI scripts as args. #589 is part of the issue, but I'm working on fixing that here Add argument to build/test scripts for additional cmake options #620
Personally I don't think the intimidation is where they are located. It might be better to have them in the root directory though, I personally am indifferent to this. The barrier for me personally is essentially how long it takes to get things setup and how much "activation energy" you need to expend to onboard. I think spoonfeeding these details makes it more accessible and a lot less motivation will be required. If I'm being honest, I am very used to just having things set up out of the box and when I want to build something I just press the little hammer button in whatever IDE/editor I'm using. I would say this is the first project where I haven't had that experience so I had to adapt(but again I'm also in my 20s so take that with a grain of salt) I am looking forward to the new scripts though. |
I couldn't agree more! I am constantly seeking ways to lower that amount of necessary activation energy. You should have seen what things were like before we even had DevContainers 🙂.
I appreciate the honest feedback! We are trying really hard to have everything just set up out of the box with our devcontainers and getting feedback from external contributors like you is the only way we know how good of a job we're doing. My mental model for how things should work in an ideal world is:
I'm curious if you think that meets the threshold for minimal activation energy or if there are further things you'd like to see? You'd mentioned being able to click a button in the IDE. I think this is possible with VSCode build tasks, but I haven't looked into it much yet, so I'll start looking into it. |
Haha I actually don't even use the devcontainers tbh. I already had my cuda toolkit set up so it was pretty straight forward iirc.
I want to just make a disclaimer here and say that overall my experience with cccl has been really positive and contributing has been fun. I hope I didn't give off the impression that it's hard to get into, because I think I got acclimated very very quickly. As for the button clicking, it's important to note that it takes initial set up in other projects so that even works in the first place. With cccl you can just copy paste the command get things going from the get go alongside dev containers. So your mental model imo is very good and should take priority over this. I am but a single data point, so I wouldn't weigh too heavily on it. Ensuring that dev containers work from the get go alongside just being able to compile your code and getting quick feedback on whether or not you made a mistake are the most important things for me. I also really like having discord channels too, and requires a lot less motivation on my end than opening up a github issue, for example, because I'm too impatient to coordinate that way and can't be as informal as I am on discord. The discord channel is honestly, the most helpful thing for my onboarding personally. I think cccl might struggle to get contributors as a consequence of the learning curve and the problem space it has to solve. At some point, lowering the activation energy will have diminishing returns because that isn't enough for someone to learn the codebase and be useful. Like I personally don't like having to walk through the macros in cccl because I have a harder time "mentally" compiling how it works comapred to regular code. But that could also be, because I'm inexperienced. Maybe more documentation on macros would be helpful? Perhaps as I'm tackling issues, I could write a comment asking how a macro works, and once I've figured it out, I can document the macro in that same PR. Another thing is perhaps just a small TLDR on the main readme on how to just get things set up locally might be helpful in reducing "activation energy"(sorry i don't know how else to describe this) by a lot. The docs are already great, but maybe this is food for thought. Hope that helps! Lmk if I wasn't clear. |
Description
I feel like having these commands available in the docs makes it easier for people to get into contributing. The CI scripts might intimidate people away and aren't suitable for using them to check if your code compiles because they do work before it gets to that building stage in the first place.
Just a rough draft, wanted to see if collaborators felt it to be beneficial. Wording can be improved as well.