[Partially in reply to Matthieu Moy's https://lore.kernel.org/git/6a5152c1-7bb4-220c-cdce-33e93ea9c7c6@xxxxxxxxxxxxx/, but it seems more useful to continue here in the v3 thread] On Thu, Apr 07 2022, COGONI Guillaume wrote: > Add a mention to the README and the init.sh in Documentation/ > MyFirstContribution.txt and a part to convince a newcomer that VS Code > can be helpful. Aside from this specific addition of a section about VSCode it says at the top of of Documentation/MyFirstContribution.txt: This tutorial aims to summarize the following documents, but the reader may find useful additional context: - `Documentation/SubmittingPatches` - `Documentation/howto/new-command.txt` Should we have anything in MyFirstContribution.txt that isn't already covered there per that statement at the top? [Combining replies at this point] On Thu, Apr 07 2022, Matthieu Moy wrote: > On 4/6/22 10:47, Ævar Arnfjörð Bjarmason wrote: >> On Wed, Apr 06 2022, COGONI Guillaume wrote: >> I really don't mind having some guide for VSCode in our developer >> documentation, but I think if we (as a free software project) are >> recommending proprietary software we should put that in some context >> where we explain if/why it's needed, and if free alternatives are also >> suitable. > > Note that VS Code is mostly open source (the pre-compiled binaries are > proprietary, but the source code is MIT licenced, > https://github.com/Microsoft/vscode). Not to be confused with Visual > Studio, which is fully proprietary, but is a totally different tool > (AFAIK, they only share the name). This patch specifically proposed to link to the propriterary version. Is there a reason we wouldn't at least recommend the fully-free version at https://github.com/VSCodium/vscodium, or at least mention it as prominently? >> I haven't used the VSCode integration you're documenting, but from the >> diff and the "gdb" mention I gather that this isn't using some "native" >> debugger of MSVC/VS's, but just using the VSCode editor as a wrapper for >> gdb? > > Yes (gdb or lldb under the hood). As usual, it adds a GUI layer, but > also a configuration layer where you specify how to launch the > debugger in a launch.json file, and this is where the little script in > contrib/ is handy to generate a launch.json adapted for Git. > >> If that's the case wouldn't it suffice to link to some generic getting >> started guide for debuggers? And e.g. recommend the GDB manual, maybe >> there's a better online reference (I read it locally), but e.g.: >> https://www.sourceware.org/gdb/current/onlinedocs/gdb.html > > To me the point of the doc within Git's repo is to document > git-specific aspects, and I agree that pointing to a generic doc is > better than re-writing one. If I had written the patch I'd have made > the general paragraph on debugger benefits a bit shorter, but it's > already rather short so I'm OK with the patch in its current state. > >> Then if we're recommending GUI wrappers those are a dime a dozen, >> e.g. Emacs's GUD mode: >> https://www.gnu.org/software/emacs/manual/html_node/emacs/Debuggers.html > > To me this is out of the scope of the patch (the real point to me was > to increase the discoverability of contrib/vscode), but sure, > documenting other GUI wrappers would be nice. > [...] > + > +[[Bonus-useful-tools]] > +== Bonus - useful tools > + > +=== Visual Studio Code (VS Code) > + > +The contrib/vscode/init.sh script creates configuration files that enable > +several valuable VS Code features. See contrib/vscode/README.md for more > +information on using the script. > + > +In particular, this script enables using the VS Code visual debugger, including > +setting breakpoints, logpoints, conditional breakpoints in the editor. > +In addition, it includes the ability to see the call stack, the line of code that > +is executing and more. It is possible to visualize the variables and their values > +and change them during execution. > + > +In sum, using the built-in debugger can be particularly helpful to understand > +how Git works internally. > +It can be used to isolate certain parts of code, with this you may be able to ask > +more precises question when you are stuck. (See getting-help sections). > diff --git a/contrib/vscode/README.md b/contrib/vscode/README.md > index 8202d62035..f383c95e1f 100644 > --- a/contrib/vscode/README.md > +++ b/contrib/vscode/README.md > @@ -6,7 +6,11 @@ code editor which runs on your desktop and is available for > [Windows](https://code.visualstudio.com/docs/setup/windows), > [macOS](https://code.visualstudio.com/docs/setup/mac) and > [Linux](https://code.visualstudio.com/docs/setup/linux). Among other languages, > -it has [support for C/C++ via an extension](https://github.com/Microsoft/vscode-cpptools). > +it has [support for C/C++ via an extension](https://github.com/Microsoft/vscode-cpptools) with > +[debugging support](https://code.visualstudio.com/docs/editor/debugging) > + > +To get help about "how to personalize your settings" read: > +[How to set up your settings](https://code.visualstudio.com/docs/getstarted/settings) Two things: First I think (disclaimer: being on the Git PLC this is just my opinion) that as a prominent free software project, and being under the Software Freedom Conservancy umbrella whose mission is (https://sfconservancy.org/): [...] fostering free and open source software (FOSS) projects, driving initiatives that actively make technology more inclusive, and advancing policy strategies that defend FOSS (such as copyleft). So, maybe I'm just an old free software radical, but I believe in interpreting that broadly. I.e. if we're recommending third-party software we should prefer free alternatives, which doesn't mean that we can't mention proprietary software, just that we shouldn't be encouraging it when a free alternative will do. But secondly, and everything here would apply if VSCode were replaced by GNU Emacs and its GUD mode, so it's not about free software on VSCode at all: This whole addition just seems like it's recommending a needlessly complex way to get to having a C debugger installed. Leaving aside completely *where* we should put such a thing I'd expect something much more like: BEGIN QUOTE == Using debuggers == You'll probably find it useful to use a debugger to interactively inspect your code as it's running. There's numerous such debuggers, and you may even have one installed already along with your development toolchain. The GNU debugger (gdb) is probably the most common one command-line debugger, along with the LLDB debugger (lldb): https://www.sourceware.org/gdb/ https://lldb.llvm.org/ === GUIs === Some users find using such a debugger to be rather "bare bones" on the command-line, but there's numerous GUIs or "front-ends" for them available. You may even find that your editort (e.g. GNU emacs) ships with such a frontend already. You may find a listing of some at (some of these work with lldb as well as gdb): http://sourceware.org/gdb/wiki/GDB%20Front%20Ends We also have helper code in-tree to launch debuggers from some editors. If you use on of these editors you may find that handy: VSCode: contrib/vscode/README.md === Debugging test failures === If you'd like to start an interactive debugger at the ponit where a test fails you may find the "debug" wrapper in t/test-lib-functions.sh useful for that. END QUOTE I.e. it really shouldn't be the goal of a section on debuggers to "convince a newcomer that VS Code can be helpful", or that Emacs is helpful or whatever. Let's instead discuss the general topic at hand. The proposed addition buries the lede in that regard. I.e. it's not made clear to the reader that we're just suggesting yet another interface for gdb, so a beginning contributor might go through it, only to find that all they needed was gdb, and they had that installed already.
