Skip to content

docs: add macos instruction, update blocks, misc changes #17642

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 11 commits into from
Closed

docs: add macos instruction, update blocks, misc changes #17642

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
22d3139
doc: update macos instruction
xepozz Jan 30, 2025
5422adc
ignore intellij idea config dir
xepozz Jan 30, 2025
70c451f
doc: wrap shell commands into language specific section
xepozz Jan 30, 2025
bd548d8
doc: add example how to run specific tests dirs
xepozz Jan 30, 2025
e817be8
doc: fix typo
xepozz Jan 30, 2025
4b0ce1e
doc: remove undefined package instruction
xepozz Jan 30, 2025
e47a821
doc: change example dir
xepozz Feb 2, 2025
5a339c5
doc: rewrite doc about speeding build
xepozz Feb 2, 2025
69c83b7
doc: add missing dependencies for macos
xepozz Feb 2, 2025
0cebe9c
Merge branch 'master' into update-docs
xepozz May 6, 2025
79e5cab
Update README.md
xepozz May 6, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .gitignore
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -290,6 +290,11 @@ tmp-php.ini
/junit.out.xml
/.ccache/

# ------------------------------------------------------------------------------
# Intellij IDEA configuration directory
# ------------------------------------------------------------------------------
/.idea
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This belongs in your personal gitignore.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Moved gitignore changes into the separate PR: #18669

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

# 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).

Copy link
Contributor

@hakre hakre Jul 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.


# ------------------------------------------------------------------------------
# Special cases to invert previous ignore patterns
# ------------------------------------------------------------------------------
Expand Down
49 changes: 37 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,28 +42,43 @@ a default build, you will additionally need libxml2 and libsqlite3.

On Ubuntu, you can install these using:

sudo apt install -y pkg-config build-essential autoconf bison re2c \
libxml2-dev libsqlite3-dev
```shell
sudo apt install -y pkg-config build-essential autoconf bison re2c libxml2-dev libsqlite3-dev
```

On MacOS, you can install these using:

```shell
brew install autoconf bison re2c iconv
```

On Fedora, you can install these using:

sudo dnf install re2c bison autoconf make libtool ccache libxml2-devel sqlite-devel
```shell
sudo dnf install re2c bison autoconf make libtool ccache libxml2-devel sqlite-devel
```

Generate configure:

./buildconf
```shell
./buildconf
```

Configure your build. `--enable-debug` is recommended for development, see
`./configure --help` for a full list of options.

# For development
./configure --enable-debug
# For production
./configure
```shell
# For development
./configure --enable-debug
# For production
./configure
```

Build PHP. To speed up the build, specify the maximum number of jobs using `-j`:

make -j4
```shell
make -j$(nproc)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.)

```

The number of jobs should usually match the number of available cores, which
can be determined using `nproc`.
Expand All @@ -76,21 +91,31 @@ successful compilation of the sources to run this test suite.
It is possible to run tests using multiple cores by setting `-jN` in
`TEST_PHP_ARGS`:

make TEST_PHP_ARGS=-j4 test
```shell
make TEST_PHP_ARGS=-j4 test
```

Shall run `make test` with a maximum of 4 concurrent jobs: Generally the maximum
number of jobs should not exceed the number of cores available.

Use `TESTS` variable to tests only specific directories:

```shell
make TESTS=Zend/tests/throw/ test
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Contributor

@hakre hakre Jul 25, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

```

The [qa.php.net](https://qa.php.net) site provides more detailed info about
testing and quality assurance.

## Installing PHP built from source

After a successful build (and test), PHP may be installed with:

make install
```shell
make install
```

Depending on your permissions and prefix, `make install` may need super user
Depending on your permissions and prefix, `make install` may need superuser
permissions.

## PHP extensions
Expand Down