Add directory structure to the contributing docs

This patch adds a php-src directory structure introduction to the
contributing guidelines. Thanks to the discussion at [1] and PHP
manual.

[1] https://github.com/php/php-src/pull/3520

1 files changed, 125 insertions, 0 deletions

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 33e86dd69a..1ee4df7c18 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -76,3 +76,128 @@ issues.
 Although not a formal channel, you can also find a number of core developers on
 the #php.pecl channel on [EFnet](http://www.efnet.org/). Similarly, many
 documentation writers can be found on #php.doc.
+
+## PHP source code directory structure
+
+PHP source code also includes several files generated during development and
+several parts where maintenance is happening upstream in their respective
+locations.
+
+```bash
+<php-src>/
+ ├─ .git/                           # Git configuration and source directory
+ └─ TSRM/                           # Thread Safe Resource Manager
+    └─ m4/                          # https://github.com/autoconf-archive/autoconf-archive
+       └─ ax_func_which_gethostbyname_r.m4
+    └─ ...
+ └─ Zend/                           # Zend Engine
+    ├─ zend_language_scanner.c      # Generated by re2c
+    ├─ zend_language_scanner_defs.h # Generated by re2c
+    ├─ zend_ini_scanner.c           # Generated by re2c
+    ├─ zend_ini_scanner_defs.h      # Generated by re2c
+    ├─ zend_vm_execute.h            # Generated by `Zend/zend_vm_gen.php`
+    ├─ zend_vm_opcodes.c            # Generated by `Zend/zend_vm_gen.php`
+    ├─ zend_vm_opcodes.h            # Generated by `Zend/zend_vm_gen.php`
+    └─ ...
+ ├─ appveyor/                       # Appveyor CI service files
+ └─ build/                          # *nix build system files
+    ├─ ax_check_compile_flag.m4     # https://github.com/autoconf-archive/autoconf-archive
+    ├─ ax_gcc_func_attribute.m4     # https://github.com/autoconf-archive/autoconf-archive
+    ├─ libtool.m4                   # https://git.savannah.gnu.org/cgit/libtool.git
+    ├─ shtool                       # https://www.gnu.org/software/shtool/
+    └─ ...
+ └─ ext/                            # PHP core extensions
+    └─ bcmath/
+       ├─ libbcmath/                # Forked and maintained in php-src
+       └─ ...
+    └─ curl/
+       ├─ sync-constants.php        # The curl symbols checker
+       └─ ...
+    └─ date/
+       └─ lib/                      # Bundled datetime library https://github.com/derickr/timelib
+          ├─ parse_date.c           # Generated by re2c 0.15.3
+          ├─ parse_iso_intervals.c  # Generated by re2c 0.15.3
+          └─ ...
+       └─ ...
+    └─ fileinfo/
+       ├─ libmagic/                 # Modified libmagic https://github.com/file/file
+       ├─ data_file.c               # Generated by `ext/fileinfo/create_data_file.php`
+       ├─ libmagic.patch            # Modifications patch from upstream libmagic
+       ├─ magicdata.patch           # Modifications patch from upstream libmagic
+       └─ ...
+    └─ gd/
+       ├─ libgd/                    # Bundled and modified GD library https://github.com/libgd/libgd
+       └─ ...
+    └─ json/
+       ├─ json_parser.tab.c         # Generated by bison
+       ├─ json_parser.tab.h         # Generated by bison
+       ├─ json_scanner.c            # Generated by re2c
+       ├─ php_json_scanner_defs.h   # Generated by re2c
+       └─ ...
+    └─ mbstring/
+       ├─ libmbfl/                  # Forked and maintained in php-src
+       ├─ oniguruma/                # Bundled https://github.com/kkos/oniguruma
+       ├─ oniguruma.patch           # Modifications patch from upstream oniguruma
+       ├─ unicode_data.h            # Generated by `ext/mbstring/ucgendat/ucgendat.php`
+       └─ ...
+    └─ pcre/
+       ├─ pcre2lib/                 # https://www.pcre.org/
+       └─ ...
+    └─ pdo/
+       ├─ pdo_sql_parser.c          # Generated by re2c
+       └─ ...
+    └─ phar/
+       ├─ phar_path_check.c         # Generated by re2c
+       └─ ...
+    └─ skeleton/                    # Skeleton for developing new extensions with `ext/ext_skel.php`
+       └─ ...
+    └─ sqlite3/
+       ├─ libsqlite/                # https://www.sqlite.org mirror: https://github.com/mackyle/sqlite
+       └─ ...
+    └─ standard/
+       └─ html_tables/
+          ├─ mappings/              # https://www.unicode.org/Public/MAPPINGS/
+          └─ ...
+       ├─ credits_ext.h             # Generated by `scripts/dev/credits`
+       ├─ credits_sapi.h            # Generated by `scripts/dev/credits`
+       ├─ html_tables.h             # Generated by `ext/standard/html_tables/html_table_gen.php`
+       ├─ url_scanner_ex.c          # Generated by re2c
+       ├─ var_unserializer.c        # Generated by re2c
+       └─ ...
+    └─ tokenizer/
+       ├─ tokenizer_data.c          # Generated by `ext/tokenizer/tokenizer_data_gen.sh`
+       └─ ...
+    └─ xmlrpc/
+       ├─ libxmlrpc/                # Forked and maintained in php-src
+       └─ ...
+    └─ zend_test                    # For testing internal APIs. Not needed for regular builds.
+       └─ ...
+    └─ zip/                         # Bundled https://github.com/pierrejoye/php_zip
+       └─ ...
+    └─ ...
+ └─ main/                           # Binding that ties extensions, SAPIs, and engine together
+    ├─ streams/                     # Streams layer subsystem
+    ├─ php_version.h                # Generated by release managers using `configure`
+    └─ ...
+ ├─ pear/                           # PEAR installation
+ └─ sapi/                           # PHP SAPI modules
+    └─ cli/
+       ├─ mime_type_map.h           # Generated by `sapi/cli/generate_mime_type_map.php`
+       └─ ...
+    └─ phpdbg/
+       ├─ phpdbg_lexer.c            # Generated by re2c
+       ├─ phpdbg_parser.c           # Generated by bison
+       ├─ phpdbg_parser.h           # Generated by bison
+       └─ ...
+    └─ ...
+ ├─ scripts/                        # php-config, phpize and internal development scripts
+ ├─ tests/                          # Core features tests
+ ├─ travis/                         # Travis CI service files
+ └─ win32/                          # Windows build system files
+    ├─ cp_enc_map.c                 # Generated by `win32/cp_enc_map_gen.exe`
+    └─ ...
+ ├─ config.guess                    # https://git.savannah.gnu.org/cgit/config.git
+ ├─ config.sub                      # https://git.savannah.gnu.org/cgit/config.git
+ ├─ ltmain.sh                       # https://git.savannah.gnu.org/cgit/libtool.git
+ └─ ...
+```