Hi Junio,

On Fri, 18 Sep 2020, Junio C Hamano wrote:

> Đoàn Trần Công Danh  <congdanhqx@gmail.com> writes:
>
> > Actually, in CMake land, people usually do this instead:
> >
> > 	mkdir build
> > 	cmake [-Ggenerator] ..
> > 	<make/ninja/msbuild>
>
> I presume you "cd build" between steps 1 & 2?  I take the "people
> usually do" is the best current practice?
>
> > Then, when they want to run something equivalent with make distclean,
> > they run:
> >
> > 	cd ..
> > 	rm -rf build
> >
> > instead.
> >
> > The change that Dscho suggested was meant for those people that run
> > CMake in same directory of source dir, which is mostly discouraged
> > in CMake land.

It is discouraged, but not disallowed.

> > In additional, CMake's default Generator in *nix is Unix Makefiles,
> > which will clash with our Makefile, and totally unsupported.
>
> I recall that our CMakeLists file asks the top-level Makefile about
> basic things so that we do not have to duplicate "list of files"
> etc.  in places, so I can understand that it would lead to a
> disaster to do "cmake -Ggenerator" at the top-level.

Indeed, when asking CMake to generate a Makefile twice, there will be a
problem.

But so far, we successfully resisted making the CMake support powerful
enough to support anything but Windows and Visual C.

> > I think the original CMake proposal didn't touch .gitignore because
> > they run in a separated build-dir.
>
> If so, not only my "do we need a matching change to CMakeLists to
> teach how to clean crufts?" becomes unnecessary, but the original
> patch that started this thread to touch .gitignore at the top level,
> does, too.
>
> I wonder what led Dscho not to follow the "create a 'build' dir and
> do things there" practice.  Judging from the fact that the "because
> they run in a separate build directory" assumption did not hold to
> somebody as experienced as Dscho, it is likely others would do the
> same.

That's because Dscho does not like the separate build directory, even if
they know that in the CMake world, it is kind of expected.

It's just that it would be super convenient for Visual Studio users to
just generate their project files in-place. That's why I started down that
road.

> What can we do to make it easier for people to discover and follow
> the best current practice?  Are there things in our build
> instruction document (e.g. the comment at the top of CMakeLists.txt)
> that needs updating?

Ideally, we would tell Visual Studio users to "just install CMake, start
its GUI, direct it to the Git source, configure and generate". Alas, it is
not that easy:

- The `SH_EXE` is not found by default (`C:\Program Files\Git\bin\sh.exe`
  should be used in the vast majority of the cases),
- If the build directory is left unspecified, the non-writable `C:\Program
  Files\CMake\bin` directory is used,
- The `compat\vcbuild\vcpkg` system is not initialized automatically, and
  even if the user initialized it, the dependencies (such as expat, zlib)
  are still not found.

I would like to make things easier, and forcing users to use a separate
build directory (that needs to be outside of the Git source tree because
our `.gitignore` does not handle it well) would go the other direction, I
fear.

In short: this `.gitignore` is but one small step in the endeavor to make
it more convenient for Visual Studio users to contribute.

Ciao,
Dscho