docs: add macos instruction, update blocks, misc changes

[xepozz]

No description provided.

[iluuu1994]

This belongs in your personal gitignore.

[xepozz]

I like how people do various smart functions and then say it's not needed now.

I have a project with commited .idea folder, I cannot mark it globally ignored.
Otherwise one line is not a problem for any project.
Moreover there are about 300 lines with long comments.
And one more thing is gitignore already has definitions for some tools like this:

# Backup copies created by various editors or development tools
*~

vim? IDEA doesn't create such files

[xepozz]

It's not a problem to remove it and keep .idea changes separately from current changes, but it's not convenient as for me

[iluuu1994]

I have a project with commited .idea folder, I cannot mark it globally ignored.

You can use git add -f .idea if you want to add a file that's globally ignored.

[iluuu1994]

Also, you do have the option to ignore it locally, for only the current .git repo, by adding it to .git/info/exclude.

[xepozz]

Do I need to create a separate PR with editing .gitignore file only?

[iluuu1994]

I don't object to this, but let's add all of the common IDEs (under the same header comment). Yes, preferably in a separate PR.

[xepozz]

Moved gitignore changes into the separate PR: #18669

[hakre]

# Backup copies created by various editors or development tools
*~

vim? IDEA doesn't create such files

Yes, that is related to editors, they are commonly with the system.

That is different to IDEs like IDEA, that typically integrate development projects, editors normally integrate with the system so that you can use the system for development. That is why you can find the local history in IDEA, and the scratch files etc. apart from the project, and *~ files temporarily in the system.

Emacs, Vim, Nano etc. are editors. The standard command name is editor, the standard environment parameter name is EDITOR.

If you wonder where that line stems from, take a look into the project excludes template of git, you will likely find it in your copy as well:

$ head .git/info/exclude
# git ls-files --others --exclude-from=.git/info/exclude
# Lines that start with '#' are comments.
# For a project mostly in C, the following would be a good set of
# exclude patterns (uncomment them if you want to use them):
# *.[oa]
# *~

At least that is my educated guess. It's also in the git repository mirror on site (Microsoft Github.)

If you read the .gitignore under version control in this project carefully, also above the line you quoted, you will find the more interesting general part about editor configurations and what the project suggests.

IMHO IDEs are not exclusive to that, nor do they require an additonal specialization of the existing excludes and includes. They just do not belong into this file. For the rationale, I'd refer to GITIGNORE(5).

[hakre]

I don't object to this, but let's add all of the common IDEs (under the same header comment). Yes, preferably in a separate PR.

There was an earlier header comment already for editor configurations, just FYI. It could have spared the whole discussion because we write since longtime, that such folders do not belong in the includes/excludes under version control.

It looks a bit to me that everyone could benefit from having better less patterns in the file then more, so that it is not that easy to overlook the most important comments in the file. Yes, it requires reading.

[iluuu1994]

You can also use TEST_PHP_ARGS for that. TEST_PHP_ARGS is an env variable while TESTS is passed as a shell argument. I'm not sure why both of these exist. Maybe @petk knows.

[hakre]

I'm not sure why both of these exist.

These are different things. TEST_PHP_ARGS is to pass additional space separated test-runner argv entries (options incl. their arguments and operands) of the run-tests.php script, while TESTS is a macro of the test target recipe.

In general the TEST_PHP_* parameters are of the test utility and should be used, the make test recipe is most of all convenience for remaking (full example):

$ make distclean
...
$ ./buildconf --force
...
$ ./configure  --enable-debug
...
$ TEST_PHP_ARGS=-j16 make -j 16 test

The test target is also remaking the main goal.

Additionally as the Makefile is being generated and the TESTS macro not documented, this is quite some detail with very little useful information for a read-me. I'll chew on that a bit, we now have the documentation about both running and writing tests in the repository.

[NattyNarwhal]

I wouldn't assume Homebrew; I'm using MacPorts instead and most instructions I see that mention brew packages will also mention the MacPorts equivalent.

[xepozz]

If you know the equivalent for MacPort instruction I'll add it

[devnexen]

That should resemble something like this

sudo port install autoconf bison re2c libiconv libxml2 sqlite3

[NattyNarwhal]

nproc isn't also always available on every Unix; macOS doesn't include it and if you install GNU coreutils from MacPorts, that'll make it available prefixed as nproc. We should probably mention the other methods that David mentions or just use a simple -j4 for everyone (and tell people to adjust.)

[xepozz]

Is there any changes I can make to push the PR further?

[nielsdos]

Removing myself as reviewer as I don't use macOS normally, someone else should re-review this.

[xepozz]

Closing this in favor of:
#18670
#18669