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 all 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 @@ -294,6 +294,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.


# ------------------------------------------------------------------------------
# Additional test build files
# ------------------------------------------------------------------------------
Expand Down
57 changes: 44 additions & 13 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -42,28 +42,49 @@ 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 libxml2 sqlite
Copy link
Member

Choose a reason for hiding this comment

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

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.

Copy link
Contributor Author

Choose a reason for hiding this comment

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

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

Copy link
Member

Choose a reason for hiding this comment

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

That should resemble something like this

sudo port install autoconf bison re2c libiconv libxml2 sqlite3

```

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` argument:

Build PHP. To speed up the build, specify the maximum number of jobs using `-j`:
On Windows:
```shell
make -j4
```

make -j4
On Unix system:
```shell
make -j4
```

The number of jobs should usually match the number of available cores, which
can be determined using `nproc`.
Expand All @@ -76,21 +97,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=tests/lang/ test
```

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
Loading