doc: Add separate productivity notes document #15348

dongcarl commented at 3:48 PM on February 5, 2019: member

Many developers have their own tools and tricks to be more productive during their cycles, so let's document the best ones so that everyone can benefit from them.

in doc/productivity.md:31 in 6e6d3a7a2e outdated

  26 | +
  27 | +The easiest way to faster compile times is to cache compiles. `ccache` is a way to do so, from its description at the time of writing:
  28 | +
  29 | +> ccache is a compiler cache. It speeds up recompilation by caching the result of previous compilations and detecting when the same compilation is being done again. Supported languages are C, C++, Objective-C and Objective-C++.
  30 | +
  31 | +Install `ccache` through your distribution's package manager, and follow the symlinks method [here](https://ccache.samba.org/manual/latest.html#_run_modes) to set it up.

MarcoFalke commented at 3:52 PM on February 5, 2019:

I don't think it is required to do any fancy symlinking. Our configure will pick up ccache on its own.

fanquake added the label Docs on Feb 5, 2019

in doc/productivity.md:57 in 6e6d3a7a2e outdated

  50 | +```
  51 | +
  52 | +If you want `make` to not limit the number of jobs that can run simultaneously, do:
  53 | +
  54 | +```sh
  55 | +make -j

MarcoFalke commented at 3:55 PM on February 5, 2019:

That could easily OOM your machine ;)

laanwj commented at 7:41 PM on February 5, 2019:

Unlimited is very likely to cause OOM problems with C++. Isn't it usually the recommendation to choose number_of_cores+1 as parallelism ? (unless for low-memory/embedded machines)

in doc/productivity.md:127 in 6e6d3a7a2e outdated

 122 | +
 123 | +When reviewing patches which change indentation in C++ files, use `git diff -w` and `git show -w`. This makes the diff algorithm ignore whitespace changes. This feature is also available on github.com, by adding `?w=1` at the end of any URL which shows a diff.
 124 | +
 125 | +When reviewing patches that change symbol names in many places, use `git diff --word-diff`. This will instead of showing the patch as deleted/added *lines*, show deleted/added *words*.
 126 | +
 127 | +When reviewing patches that move code around, try using `git diff --patience commit~:old/file.cpp commit:new/file/name.cpp`, and ignoring everything except the moved body of code which should show up as neither `+` or `-` lines. In case it was not a pure move, this may even work when combined with the `-w` or `--word-diff` options described above.

MarcoFalke commented at 3:56 PM on February 5, 2019:

for moved code, there'd also be --color-moved=dimmed-zebra

MarcoFalke commented at 3:59 PM on February 5, 2019:

example:

git diff 2ca632e5b44a8385989c8539cc4e30e60fdee16c~ 2ca632e5b44a8385989c8539cc4e30e60fdee16c --color-moved=dimmed-zebra src/test

MarcoFalke approved

dongcarl force-pushed on Feb 5, 2019

laanwj commented at 4:16 PM on February 5, 2019: member

Concept ACK, though sometimes I wonder if a wiki wouldn't be a better place for things like this. It's not that easy to maintain documentation in the repository as it has to go through the same review bottleneck as everything else (especially considering a lot of this concerns third-party tools and not our own).

But despite that, thanks for writing this!

dongcarl commented at 4:21 PM on February 5, 2019: member

@laanwj I believe GitHub allows you to create Wikis for repos, we could try that in the future :relaxed:

hebasto commented at 5:36 PM on February 5, 2019: member

Concept ACK.

dongcarl force-pushed on Feb 5, 2019

dongcarl commented at 7:49 PM on February 5, 2019: member

Addressed comments.

in doc/productivity.md:31 in 263f4b1e35 outdated

  26 | +
  27 | +The easiest way to faster compile times is to cache compiles. `ccache` is a way to do so, from its description at the time of writing:
  28 | +
  29 | +> ccache is a compiler cache. It speeds up recompilation by caching the result of previous compilations and detecting when the same compilation is being done again. Supported languages are C, C++, Objective-C and Objective-C++.
  30 | +
  31 | +Install `ccache` through your distribution's package manager, and run `./configure` with your normal flags to pick it up.

MarcoFalke commented at 8:16 PM on February 5, 2019:

this diff appears to have added new lines with trailing whitespace.
The following changes were suspected:
diff --git a/doc/productivity.md b/doc/productivity.md
@@ -0,0 +1,161 @@
+
+Install `ccache` through your distribution's package manager, and run `./configure` with your normal flags to pick it up.
^---- failure generated from test/lint/lint-whitespace.sh

dongcarl force-pushed on Feb 5, 2019

doc: Add separate productivity notes document

Many developers have their own tools and tricks to be more productive
during their cycles, so let's document the best ones so that everyone
can benefit from them.

5b76c314d6

meshcollider commented at 8:46 PM on February 5, 2019: contributor

Concept ACK, looks good so far

MarcoFalke merged this on Feb 18, 2019

MarcoFalke closed this on Feb 18, 2019

MarcoFalke referenced this in commit f78cd3dd51 on Feb 18, 2019

jasonbcox referenced this in commit 83e189e2a5 on Nov 18, 2020

PastaPastaPasta referenced this in commit 395cb61995 on Jun 27, 2021

PastaPastaPasta referenced this in commit 447ff166fb on Jun 28, 2021

DrahtBot locked this on Dec 16, 2021