diff --git a/.gitignore b/.gitignore index bb59dbe..4886176 100644 --- a/.gitignore +++ b/.gitignore @@ -29,7 +29,7 @@ configure.ac install-sh libtool ltmain.sh -Makefile +/Makefile Makefile.fragments Makefile.global Makefile.objects @@ -42,6 +42,5 @@ tmp-php.ini /conftest* /*.tgz +.virtualenv -_book/ -node_modules/ diff --git a/README.md b/README.md index d8878c4..832a379 100644 --- a/README.md +++ b/README.md @@ -3,6 +3,8 @@ PHP extension for V8 JavaScript engine [![Build Status](https://api.travis-ci.org/pinepain/php-v8.svg?branch=master)](https://travis-ci.org/pinepain/php-v8) [![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://raw.githubusercontent.com/pinepain/php-v8/master/LICENSE) +[![Docs](https://readthedocs.org/projects/php-v8/badge/)](https://php-v8.readthedocs.io) + **This extension requires PHP >= 7.1**. Last version that supports PHP 7.0 is v0.1.9. @@ -13,7 +15,7 @@ PHP extension for V8 JavaScript engine Maintaining this project takes significant amount of time and efforts. If you like my work and want to show your appreciation, please consider supporting me at https://www.patreon.com/pinepain. -Work in progress documentation could be found at https://pinepain.gitbooks.io/php-v8/content/. You can also use tests and +Work in progress documentation could be found at https://php-v8.readthedocs.io. You can also use tests and stubs as reference. ## Why (aka Rationale) @@ -181,11 +183,16 @@ Now you can build php-v8 as usual with `phpize && ./configure && make`. Don't fo ### Docs -To start writing docs you will need to get [GitBook](https://gitbook.com), just run `npm install gitbook-cli -g` and -then `gitbook serve` in project rood directory to live preview docs or `gitbook build` to build static website. See -[Setup and Installation of GitBook](https://toolchain.gitbook.com/setup.html) official GitBook manual for more; +We use [Sphinx](http://www.sphinx-doc.org/en/master/) to buld docs and [Read The Docs](https://readthedocs.org/) to host +it. + +To rebuild docs locally run in a project root: + + virtualenv -p `which python` .virtualenv + source .virtualenv/bin/activate + cd docs + make html -You may find [GitBook Editor](https://www.gitbook.com/editor) useful for docs writing and editing. ## Credits diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..e35d885 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +_build diff --git a/docs/Makefile b/docs/Makefile new file mode 100644 index 0000000..f9f2aa6 --- /dev/null +++ b/docs/Makefile @@ -0,0 +1,20 @@ +# Minimal makefile for Sphinx documentation +# + +# You can set these variables from the command line. +SPHINXOPTS = +SPHINXBUILD = sphinx-build +SPHINXPROJ = php-v8 +SOURCEDIR = . +BUILDDIR = _build + +# Put it first so that "make" without argument is like "make help". +help: + @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) + +.PHONY: help Makefile + +# Catch-all target: route all unknown targets to Sphinx using the new +# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS). +%: Makefile + @$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O) \ No newline at end of file diff --git a/docs/README.md b/docs/README.md deleted file mode 100644 index ebb57cf..0000000 --- a/docs/README.md +++ /dev/null @@ -1,57 +0,0 @@ -# PLEASE READ: - -Maintaining this project takes significant amount of time and efforts. -If you like my work and want to show your appreciation, please consider supporting me at https://www.patreon.com/pinepain. - - -# About - -[php-v8](https://github.com/pinepain/php-v8) is a PHP 7.x extension -that brings [V8](https://developers.google.com/v8/intro) JavaScript engine API to PHP with some abstraction in mind and -provides an accurate native V8 C++ API implementation available from PHP. - -**Key features:** - - provides up-to-date JavaScript engine with recent [ECMA](http://kangax.github.io/compat-table) features supported; - - accurate native V8 C++ API implementation available from PHP; - - solid experience between native V8 C++ API and V8 API in PHP; - - no magic; no assumptions; - - does what it is asked to do; - - hides complexity with isolates and contexts scope management under the hood; - - provides a both-way interaction with PHP and V8 objects, arrays and functions; - - execution time and memory limits; - - multiple isolates and contexts at the same time; - - it works. - -With this extension almost everything that the native V8 C++ API provides can be used. It provides a way to pass PHP scalars, -objects and functions to the V8 runtime and specify interactions with passed values (objects and functions only, as scalars -become js scalars too). While specific functionality will be done in PHP userland rather than in this C/C++ extension, -it lets you get into V8 hacking faster, reduces time costs and gives you a more maintainable solution. And it doesn't -make any assumptions for you, so you stay in control, it does exactly what you ask it to do. - -With php-v8 you can even implement nodejs in PHP. Not sure whether anyone should/will do this anyway, but it's doable. - -# Demo - -Here is a [Hello World][v8-hello-world] from V8 [Getting Started][v8-intro] developers guide page implemented in raw php-v8: - -```php -run($context); - -echo $result->value(), PHP_EOL; -``` - -[v8-hello-world]: https://chromium.googlesource.com/v8/v8/+/master/samples/hello-world.cc -[v8-intro]: https://developers.google.com/v8/intro -[php-v8-stubs]: https://github.com/pinepain/php-v8-stubs diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md deleted file mode 100644 index 8680f53..0000000 --- a/docs/SUMMARY.md +++ /dev/null @@ -1,11 +0,0 @@ -# Summary - -## Getting started - -* [Introduction](README.md) -* [Support this project](getting-started/donate.md) - -### Development - -* [Releasing libv8](development/release-libv8.md) -* [Releasing php-v8](development/release-php-v8.md) diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..65dfb42 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,190 @@ +# -*- coding: utf-8 -*- +# +# Configuration file for the Sphinx documentation builder. +# +# This file does only contain a selection of the most common options. For a +# full list see the documentation: +# http://www.sphinx-doc.org/en/stable/config + +# -- Path setup -------------------------------------------------------------- + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +# +# import os +# import sys +# sys.path.insert(0, os.path.abspath('.')) + +# import sys, os +# from sphinx.highlighting import lexers +# from pygments.lexers.web import PhpLexer +# +# +# lexers['php'] = PhpLexer(startinline=True, linenos=1) +# lexers['php-annotations'] = PhpLexer(startinline=True, linenos=1) +# primary_domain = 'php' + + +import sys +import os +import shlex +from sphinx.highlighting import lexers +from pygments.lexers.web import PhpLexer + +lexers['php'] = PhpLexer(startinline=True, linenos=1) + +primary_domain = 'php' +highlight_language = 'php' + +# -- Project information ----------------------------------------------------- + +project = u'php-v8' +copyright = u'2018, Bogdan Padalko' +author = u'Bogdan Padalko' + +# The short X.Y version +version = u'' +# The full version, including alpha/beta/rc tags +release = u'' + + +# -- General configuration --------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +# +# needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be +# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom +# ones. +extensions = [ + 'sphinx.ext.doctest', + 'sphinx.ext.todo', + 'sphinx.ext.coverage', + 'sphinxcontrib.phpdomain' + #'sphinxcontrib.spelling' +] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix(es) of source filenames. +# You can specify multiple suffix as a list of string: +# +# source_suffix = ['.rst', '.md'] +source_suffix = '.rst' + +# The master toctree document. +master_doc = 'index' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +# +# This is also used if you do content translation via gettext catalogs. +# Usually you set "language" from the command line for these cases. +language = None + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +# This pattern also affects html_static_path and html_extra_path . +exclude_patterns = [u'_build', 'Thumbs.db', '.DS_Store'] + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + + +# -- Options for HTML output ------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +# +html_theme = 'sphinx_rtd_theme' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +# +# html_theme_options = {} + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# Custom sidebar templates, must be a dictionary that maps document names +# to template names. +# +# The default sidebars (for documents that don't match any pattern) are +# defined by theme itself. Builtin themes are using these templates by +# default: ``['localtoc.html', 'relations.html', 'sourcelink.html', +# 'searchbox.html']``. +# +# html_sidebars = {} + + +# -- Options for HTMLHelp output --------------------------------------------- + +# Output file base name for HTML help builder. +htmlhelp_basename = 'php-v8doc' + + +# -- Options for LaTeX output ------------------------------------------------ + +latex_elements = { + # The paper size ('letterpaper' or 'a4paper'). + # + # 'papersize': 'letterpaper', + + # The font size ('10pt', '11pt' or '12pt'). + # + # 'pointsize': '10pt', + + # Additional stuff for the LaTeX preamble. + # + # 'preamble': '', + + # Latex figure (float) alignment + # + # 'figure_align': 'htbp', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, +# author, documentclass [howto, manual, or own class]). +latex_documents = [ + (master_doc, 'php-v8.tex', u'php-v8 Documentation', + u'Bogdan Padalko', 'manual'), +] + + +# -- Options for manual page output ------------------------------------------ + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + (master_doc, 'php-v8', u'php-v8 Documentation', + [author], 1) +] + + +# -- Options for Texinfo output ---------------------------------------------- + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + (master_doc, 'php-v8', u'php-v8 Documentation', + author, 'php-v8', 'One line description of project.', + 'Miscellaneous'), +] + + +# -- Extension configuration ------------------------------------------------- + +spelling_word_list_filename='spelling_wordlist.txt' + +# -- Options for todo extension ---------------------------------------------- + +# If true, `todo` and `todoList` produce output, else they produce nothing. +todo_include_todos = True diff --git a/docs/development/index.rst b/docs/development/index.rst new file mode 100644 index 0000000..48cbf7f --- /dev/null +++ b/docs/development/index.rst @@ -0,0 +1,12 @@ +=============== +Release process +=============== + +Here you can find basics to the release process + + +.. toctree:: + :maxdepth: 3 + + release-php-v8 + release-libv8 diff --git a/docs/development/release-libv8.md b/docs/development/release-libv8.md deleted file mode 100644 index 0822ccd..0000000 --- a/docs/development/release-libv8.md +++ /dev/null @@ -1,56 +0,0 @@ -We will start with building Ubuntu PPA first as it used in further CI process to validate that php-v8 is not broken. - -To track v8 changes you can use these links: - - https://github.com/v8/v8/commits/master/include/v8.h - to keep track on v8 upstream changes - - https://omahaproxy.appspot.com/ - to keep track v8 channel(version) heads and what version is used in chrome - - -## Building libv8 - -1. **Skip this step if you are updating v8 patch release version.** To bump minor v8 version (e.g. from 6.3 to 6.4), - create new `libv8-X.Y` PPA for new version. As V8 could be build for i386 but only from amd64, which is not how PPA - works, it's also make sense to keep new PPA amd64-only. Also we don't use i386 so we don't want to worry about it. -2. Update libv8 Makefile (`packaging/libv8/Makefile`) with new libv8 version by setting proper values in - `GIT_VERSION=X.Y.Z` and `NAME=libv8-X.Y` variables. -3. Commit changes with `build libv8` commit message and wait until libv8 PPA build done. -4. Don't forget to update `libv8 >= ` dependency for php-v8 PPA in `packaging/php-v8/debian/control` - and also change php-v8 PPA repo dependency to include new `libv8-X.Y` PPA - (https://launchpad.net/~pinepain/+archive/ubuntu/php-v8/+edit-dependencies), it's done by looking for ppa by full name, - e.g. `pinepain/libv8-X.Y`. - -## After libv8 PPA build done - -1. Copy fresh `libv8-X.Y` build packages from `libv8-experimental` (default target for all libv8 builds we trigger) - to it `libv8-X.Y` PPA. Do not rebuild, just copy binaries. -2. **Wait for packages copied and published!** -3. Build [pinepain/libv8](https://github.com/pinepain/dockerfiles/tree/master/libv8) docker image, tag it with the - relevant v8 full version and push to Docker Hub. -4. You may want to set proper `V8` version in `php-v8` by updating it in `.travis.yml`. -5. Make sure you have proper `php-v8` version set in `packaging/Dockerfile` under `V8` constant. - -## After docker images rebuilt/published - -1. Update min required `libv8` version in [php-v8](https://github.com/pinepain/php-v8)/config.m4, `V8_MIN_API_VERSION_STR=X.Y.Z`. -2. If there was new docker images published, update reference to them in [php-v8](https://github.com/pinepain/php-v8)/.travis.yml - and in [php-v8](https://github.com/pinepain/php-v8)/Dockerfile, and set proper `V8` and `TAG` value there. -3. Update reference to `v8@X.Y` in [php-v8](https://github.com/pinepain/php-v8)/CMakeLists.txt on minor version bump. -4. Also, update references to v8 version in [php-v8](https://github.com/pinepain/php-v8)/scripts/provision/provision.sh, - it's normally could be done by replacing old version with new, e.g. `6.3` => `6.4`. -5. On every version bump update [php-v8](https://github.com/pinepain/php-v8)/README.md file with proper min v8 version required/tested. -6. If you use vagrant, re-provision your local dev env at this step to fetch/add new `libv8` version. - It's generally a good idea to remove old `libv8` versions as well and remove their PPA from apt sources list at this point. -7. **Make sure you tested [php-v8](https://github.com/pinepain/php-v8) locally first before pushing to remote**, - upgrading v8 could be tricky as it may break BC even in patch releases (that's why we started to have separate - PPAs for minor version to somehow couple with this issue in minor releases). -8. Note, that doing all this in a separate branch and merging that later into master is a nice and safe idea - (note, you may skip PR overhead and do fast-forward merge locally to master). -9. Commit message should state that it is v8 version bump, e.g. `Require libv8 >= X.Y.Z` -10. Push changes and make sure build is green. If not, fix code/update tests and repeat. - - -## Building packages for macOS Homebrew - -1. **Skip this step if you are updating v8 patch release version.** If it is a minor version bump, create new `v8@X.Y` formula. -2. **Skip this step if you are updating v8 patch release version.** Create new `v8:X.Y` Package on bintray for it. -2. Remove/reset formula `revision` if it is version bump and not rebuild. -3. Build `v8@X.Y` (locally or with travis if it provides releavent macOS version) and publish. diff --git a/docs/development/release-libv8.rst b/docs/development/release-libv8.rst new file mode 100644 index 0000000..c37e8d8 --- /dev/null +++ b/docs/development/release-libv8.rst @@ -0,0 +1,67 @@ +************* +Release libv8 +************* + +We will start with building Ubuntu PPA first as it used in further CI process to validate that ``php-v8`` is not broken. + +To track v8 changes you can use these links: + +* https://github.com/v8/v8/commits/master/include/v8.h - to keep track on v8 upstream changes +* https://omahaproxy.appspot.com/ - to keep track v8 channel(version) heads and what version is used in chrome + +Building libv8 +============== + +#. **Skip this step if you are updating v8 patch release version.** To bump minor v8 version (e.g. from 6.3 to 6.4), + create new ``libv8-X.Y`` PPA for new version. As V8 could be build for ``i386`` but only from ``amd64``, which is not how PPA + works, it's also make sense to keep new PPA ``amd64``-only. Also we don't use ``i386`` so we don't want to worry about it. +#. Update libv8 Makefile (``packaging/libv8/Makefile``) with new libv8 version by setting proper values in + ``GIT_VERSION=X.Y.Z`` and ``NAME=libv8-X.Y`` variables. +#. Commit changes with ``build libv8`` commit message and wait until libv8 PPA build done. +#. Don't forget to update ``libv8 >= `` dependency for ``php-v8`` PPA in ``packaging/php-v8/debian/control`` + and also change ``php-v8`` PPA repository dependency to include new ``libv8-X.Y`` PPA + (https://launchpad.net/~pinepain/+archive/ubuntu/php-v8/+edit-dependencies), it's done by looking for ppa by full name, + e.g. ``pinepain/libv8-X.Y``. + +After libv8 PPA build done +========================== + +#. Copy fresh ``libv8-X.Y`` build packages from ``libv8-experimental`` (default target for all libv8 builds we trigger) + to it ``libv8-X.Y`` PPA. Do not rebuild, just copy binaries. +#. **Wait for packages copied and published!** +#. Build `pinepain/libv8`_ docker image, tag it with the + relevant v8 full version and push to Docker Hub. +#. You may want to set proper ``V8`` version in ``php-v8`` by updating it in ``.travis.yml``. +#. Make sure you have proper ``php-v8`` version set in ``packaging/Dockerfile`` under ``V8`` constant. + +After docker images rebuilt/published +===================================== + +#. Update min required ``libv8`` version in `php-v8`_ ``config.m4``, ``V8_MIN_API_VERSION_STR=X.Y.Z``. +#. If there was new docker images published, update reference to them in `php-v8`_ ``.travis.yml`` + and in `php-v8`_ ``Dockerfile``, and set proper ``V8`` and ``TAG`` value there. +#. Update reference to ``v8@X.Y`` in `php-v8`_ `CMakeLists.txt` on minor version bump. +#. Also, update references to v8 version in `php-v8`_/scripts/provision/provision.sh, + it's normally could be done by replacing old version with new, e.g. ``6.3`` => ``6.4``. +#. On every version bump update `php-v8`_ ``README.md`` file with proper min v8 version required/tested. +#. If you use vagrant, re-provision your local development environment at this step to fetch/add new ``libv8`` version. + It's generally a good idea to remove old ``libv8`` versions as well and remove their PPA from apt sources list at this point. +#. **Make sure** you tested `php-v8`_ locally first before pushing to remote, + upgrading v8 could be tricky as it may break BC even in patch releases (that's why we started to have separate + PPAs for minor version to somehow couple with this issue in minor releases). +#. Note, that doing all this in a separate branch and merging that later into master is a nice and safe idea + (note, you may skip PR overhead and do fast-forward merge locally to master). +#. Commit message should state that it is v8 version bump, e.g. ``Require libv8 >= X.Y.Z`` +#. Push changes and make sure build is green. If not, fix code/update tests and repeat. + + +Building packages for macOS Homebrew +==================================== + +#. **Skip this step if you are updating v8 patch release version.** If it is a minor version bump, create new ``v8@X.Y`` formula. +#. **Skip this step if you are updating v8 patch release version.** Create new ``v8:X.Y`` Package on bintray for it. +#. Remove/reset formula ``revision`` if it is version bump and not rebuild. +#. Build ``v8@X.Y`` (locally or with TravisCI if it provides relevant macOS version) and publish. + +.. _php-v8: https://github.com/pinepain/php-v8 +.. _pinepain/libv8: https://github.com/pinepain/dockerfiles/tree/master/libv8 diff --git a/docs/development/release-php-v8.md b/docs/development/release-php-v8.md deleted file mode 100644 index a892aa1..0000000 --- a/docs/development/release-php-v8.md +++ /dev/null @@ -1,50 +0,0 @@ -# GitHub release - -1. Make sure current state is ready for release: - * All relevant PR merged and issues closed. - * Build passed. -2. Prepare release notes by creating release draft on github. -3. Update `PHP_V8_VERSION` to have desired version and set `PHP_V8_REVISION` to `release` in `php_v8.h`. -4. Run `./scripts/refresh-package-xml.php -f` to update `package.xml` with proper `php-v8` version and update directories - and files tree. -5. Update `package.xml` `` with release notes. Keep eye on special characters to properly escape them, - e.g. `>` should be written as `>` instead. -6. Commit all changes with `Prepare X.Y.Z release` commit message. -7. Push this commit and make sure it will pass the build. -8. Tag it with `vX.Y.Z` tag and push. Create github release from a draft prepared in step above. -9. Close relevant milestone, if any. -10. Run `./scripts/subsplit.sh` to update `php-v8-stubs` which are available in a separate read-only repository to match - packagist and composer expectations. - -# PECL release - -1. Run `pecl package` in your build machine (it's normally vagrant box used for `php-v8` development). It should create - `v8-X.Y.Z.tgz` file. -2. Log in to PECL and upload file from previous step at https://pecl.php.net/release-upload.php. Verify that release info - is accurate and confirm release. - -# Ubuntu PPA release - -1. Copy targeted `libv8-X.Y` build to `php` ppa without rebuild, just copy. -2. Make sure you have proper PHP and php-v8 PPA dependencies set in https://launchpad.net/~pinepain/+archive/ubuntu/php-v8/+edit-dependencies -3. Make sure you have proper `php-v8` version set in `packaging/Dockerfile` under `V8` constant. -4. In `packaging/php-v8/Makefile` set proper `VERSION=X.Y.Z` -5. Make sure you have valid `libv8` dependency in `packaging/php-v8/debian/control` file. -6. Commit changes with `build php-v8` commit message and wait until libv8 PPA build done. -7. Copy `php-v8` packages to `pinepain/php` PPA, do not rebuild, just copy. -8. After they get copied, feels free to remove **old** `libv8` packages from `pinepain/php` ppa. - -# macOS Homebrew release - -1. Update `php7*-v8` formulae **one by one** to have proper `depends_on 'v8@X.Y'` - and `v8_prefix=Formula['v8@X.Y'].opt_prefix` values. -2. If you want to rebuild existent version, add/increment `revision` in formula body. -3. If version has already been published to bintray and you absolutely sure it needs to be re-built without revision. - bump, you will need to delete such version from bintray first. - -# After all - -1. Update [js-sandbox](https://github.com/pinepain/js-sandbox)/`.travis.yml` and `.scrutinizer.yml` - to refer to new `php-v8` version and to relevant `libv8` PPA and packages. -2. Update `PHP_V8_VERSION` to the next version and set `PHP_V8_REVISION` to `dev` in `php_v8.h`. -3. Commit changes with `Back to dev [skip ci]` message and push them to master. diff --git a/docs/development/release-php-v8.rst b/docs/development/release-php-v8.rst new file mode 100644 index 0000000..a185f64 --- /dev/null +++ b/docs/development/release-php-v8.rst @@ -0,0 +1,64 @@ +************** +Release php-v8 +************** + +GitHub release +============== + +#. Make sure current state is ready for release: + + - All relevant PR merged and issues closed. + - Build passed. + +#. Prepare release notes by creating release draft on github. +#. Update ``PHP_V8_VERSION`` to have desired version and set ``PHP_V8_REVISION`` to ``release`` in ``php_v8.h``. +#. Run ``./scripts/refresh-package-xml.php -f`` to update ``package.xml`` with proper ``php-v8`` version and update directories + and files tree. +#. Update ``package.xml`` ```` with release notes. Keep eye on special characters to properly escape them, + e.g. ``>`` should be written as ``>`` instead. +#. Commit all changes with ``Prepare X.Y.Z release`` commit message. +#. Push this commit and make sure it will pass the build. +#. Tag it with ``vX.Y.Z`` tag and push. Create github release from a draft prepared in step above. +#. Close relevant milestone, if any. +#. Run ``./scripts/subsplit.sh`` to update ``php-v8-stubs`` which are available in a separate read-only repository to match + packagist and composer expectations. + +# PECL release + +#. Run ``pecl package`` in your build machine (it's normally vagrant box used for ``php-v8`` development). It should create + ``v8-X.Y.Z.tgz`` file. +#. Log in to PECL and upload file from previous step at https://pecl.php.net/release-upload.php. Verify that release info + is accurate and confirm release. + +Ubuntu PPA release +================== + +#. Copy targeted ``libv8-X.Y`` build to ``php`` ppa without rebuild, just copy. +#. Make sure you have proper PHP and ``php-v8`` PPA dependencies set in https://launchpad.net/~pinepain/+archive/ubuntu/php-v8/+edit-dependencies +#. Make sure you have proper ``php-v8`` version set in ``packaging/Dockerfile`` under ``V8`` constant. +#. In ``packaging/php-v8/Makefile`` set proper ``VERSION=X.Y.Z`` +#. Make sure you have valid ``libv8`` dependency in ``packaging/php-v8/debian/control`` file. +#. Commit changes with ``build php-v8`` commit message and wait until libv8 PPA build done. +#. Copy ``php-v8`` packages to ``pinepain/php`` PPA, do not rebuild, just copy. +#. After they get copied, feels free to remove **old** ``libv8`` packages from ``pinepain/php`` ppa. + +macOS Homebrew release +====================== + +#. Update ``php7*-v8`` formula **one by one** to have proper ``depends_on 'v8@X.Y'`` + and ``v8_prefix=Formula['v8@X.Y'].opt_prefix`` values. +#. If you want to rebuild existent version, add/increment ``revision`` in formula body. +#. If version has already been published to bintray and you absolutely sure it needs to be re-built without revision. + bump, you will need to delete such version from bintray first. + +TODO: docker release + +After all +========= + +#. Update `js-sandbox`_ ``.travis.yml`` and ``.scrutinizer.yml`` + to refer to new ``php-v8`` version and to relevant ``libv8`` PPA and packages. +#. Update ``PHP_V8_VERSION`` to the next version and set ``PHP_V8_REVISION`` to ``dev`` in ``php_v8.h``. +#. Commit changes with ``Back to dev [skip ci]`` message and push them to master. + +.. _js-sandbox: https://github.com/pinepain/js-sandbox diff --git a/docs/getting-started/donate.md b/docs/getting-started/donate.rst similarity index 89% rename from docs/getting-started/donate.md rename to docs/getting-started/donate.rst index 48a7ca4..7c4924d 100644 --- a/docs/getting-started/donate.md +++ b/docs/getting-started/donate.rst @@ -1,4 +1,5 @@ -# PLEASE READ +Please read +----------- Maintaining this project takes significant amount of time and efforts. If you like my work and want to show your appreciation, please consider supporting me at https://www.patreon.com/pinepain. diff --git a/docs/getting-started/index.rst b/docs/getting-started/index.rst new file mode 100644 index 0000000..e9ad93c --- /dev/null +++ b/docs/getting-started/index.rst @@ -0,0 +1,151 @@ +*************** +Getting started +*************** + +About +===== + +`php-v8`_ is a PHP 7.x extension that brings `V8`_ JavaScript engine API to PHP with some abstraction in mind and +provides an accurate native V8 C++ API implementation available from PHP. + +Key features: +------------- + + - provides up-to-date JavaScript engine with recent `ECMA`_ features supported; + - accurate native V8 C++ API implementation available from PHP; + - solid experience between native V8 C++ API and V8 API in PHP; + - no magic; no assumptions; + - does what it is asked to do; + - hides complexity with isolates and contexts scope management under the hood; + - provides a both-way interaction with PHP and V8 objects, arrays and functions; + - execution time and memory limits; + - multiple isolates and contexts at the same time; + - it works. + +With this extension almost everything that the native V8 C++ API provides can be used. It provides a way to pass PHP scalars, +objects and functions to the V8 runtime and specify interactions with passed values (objects and functions only, as scalars +become js scalars too). While specific functionality will be done in PHP user space rather than in this C/C++ extension, +it lets you get into V8 hacking faster, reduces time costs and gives you a more maintainable solution. And it doesn't +make any assumptions for you, so you stay in control, it does exactly what you ask it to do. + +With php-v8 you can even implement NodeJs in PHP. Not sure whether anyone should/will do this anyway, but it's doable. + +Demo +==== + +Here is a `Hello World`_ from V8 `Getting Started` developers guide page implemented in raw php-v8: + +.. code:: php + + run($context); + + echo $result->value(), PHP_EOL; + +Installation +============ + + +Requirements +------------ + +V8 +"" + +You will need a recent v8 Google JavaScript engine version installed. At this time v8 >= 6.6.313 required. + +PHP +""" + +This extension is PHP7-only. It works and tested with both PHP 7.0 and PHP 7.1. + +OS +""" + +This extension works and tested on x64 Linux and macOS. As of written it is Ubuntu 16.04 LTS Xenial Xerus, amd64 +and macOS 10.12.5. Windows is not supported at this time. + +Quick guide +----------- + +Docker +"""""" + +There is default ``pinepain/php-v8`` docker image with basic dependencies to evaluate and play with php-v8: + +.. code-block:: bash + + docker run -it pinepain/php-v8 bash -c "php test.php" + + +Ubuntu +"""""" + +There is + +.. code-block:: bash + + $ sudo add-apt-repository -y ppa:ondrej/php + $ sudo add-apt-repository -y ppa:pinepain/php + $ sudo apt-get update -y + $ sudo apt-get install -y php7.2 php-v8 + $ php --ri v8 + + +While `pinepain/php `_ PPA targets to contain all necessary +extensions with dependencies, you may find following standalone PPAs useful: + +- `pinepain/libv8-6.6 `_ +- `pinepain/libv8-experimental `_ +- `pinepain/php-v8 `_ + + + +OS X (homebrew) +""""""""""""""" + +.. code-block:: bash + + $ brew tap homebrew/dupes + $ brew tap homebrew/php + $ brew tap pinepain/devtools + $ brew install php71 php71-v8 + $ php --ri v8 + +For macOS php-v8 formulae and dependencies provided by `pinepain/devtools `_ tap. + +Building php-v8 from sources +---------------------------- + +.. code-block:: bash + + git clone https://github.com/pinepain/php-v8.git + cd php-v8 + phpize && ./configure && make + make test + +To install extension globally run + +.. code-block:: bash + + $ sudo make install + +.. _V8: https://developers.google.com/v8/intro +.. _php-v8: https://github.com/pinepain/php-v8 +.. _Hello World: https://chromium.googlesource.com/v8/v8/+/master/samples/hello-world.cc +.. _Getting Started: https://developers.google.com/v8/intro +.. _php-v8-stubs: https://github.com/pinepain/php-v8-stubs +.. _ECMA: http://kangax.github.io/compat-table diff --git a/docs/getting-started/performance-tricks.rst b/docs/getting-started/performance-tricks.rst new file mode 100644 index 0000000..af52558 --- /dev/null +++ b/docs/getting-started/performance-tricks.rst @@ -0,0 +1,261 @@ +****************** +Performance tricks +****************** + +If you use ``php-v8`` extension for short-lived tasks or you have your :class:`Context` likely to be long-living enough +so that ``V8`` runtime optimizations won't have significant impact, you can still improve your performance. + +Important note: all caching techniques are V8 version-specific and platform specific, some caches won't even work on +different CPU with different instructions set, you have to test following techniques for your environment and +infrastructure and be ready to fallback to raw, cache-less flow. + + +Let's say you have an typical Hello, world! script: + +.. code:: php + + run($context); + + echo $result->value(), PHP_EOL; + +Let's reshape it a bit to make it more suitable for further tweaks by introducing :class:`ScriptCompiler`: + +.. code:: php + + run($context); + + echo $result->value(), PHP_EOL; + +Script code cache +================= + +Using script code cache could boost your performance from 5% to 25% or even more, itlargely depends on your script and +host. On slower machines it may give you better result in terms of performance gain %%, while on faster it may be not so +large, according to performance benchmark. + +.. code:: php + + isRejected()) { + throw new RuntimeException('Script code cache rejected!'); + } + + $result = $script->run($context); + + echo $result->value(), PHP_EOL; + + +Isolate startup data +==================== + +Startup data can speedup your context creation by populating them with script run result. It can save from 1% to 3%, so +it's not so effective as script code cache, however, the benchmark was done on so complex example so if you have a lot +of entities that you need to bootstrap your context with, your saving may be more. + +.. code:: php + + run($context); + + echo $result->value(), PHP_EOL; + + +Combining both approaches +========================= + +Combining both techniques is you friend in boosting performance: + +.. code:: php + + isRejected()) { + throw new RuntimeException('Script code cache rejected!'); + } + + $script = ScriptCompiler::compile($context, $source); + + $result = $script->run($context); + + echo $result->value(), PHP_EOL; + +Benchmarks +========== + + +Note, that your mileage may varies so you are highly encouraged to run benchmarks located under project's root ``/pref`` +folder by yourself on your hardware, in your infra and even with your js script. + +From Ubuntu in Docker on macOS +------------------------------ +4 cores, 16Gb memory + +.. code:: bash + + # php -v + PHP 7.2.2-3+ubuntu16.04.1+deb.sury.org+1 (cli) (built: Feb 6 2018 16:11:23) ( NTS ) + Copyright (c) 1997-2018 The PHP Group + Zend Engine v3.2.0, Copyright (c) 1998-2018 Zend Technologies + with Zend OPcache v7.2.2-3+ubuntu16.04.1+deb.sury.org+1, Copyright (c) 1999-2018, by Zend Technologies + + # php --ri v8 + V8 support => enabled + Version => v0.2.1-master-dev + Revision => 5d7c3e4 + Compiled => Feb 25 2018 @ 11:29:00 + + V8 Engine Compiled Version => 6.6.313 + V8 Engine Linked Version => 6.6.313 + + +*Less is better* + ++---------------------------------+-------------+----------+--------+---------------------------+ +| subject | mode | stdev | rstdev | diff (*less is better*) | ++=================================+=============+==========+========+===========================+ +| Cold Isolate, no code cache | 3,602.599us | 49.778us | 1.38% | +26.98% | ++---------------------------------+-------------+----------+--------+---------------------------+ +| Cold Isolate, with code cache | 2,885.638us | 39.775us | 1.36% | +2.86% | ++---------------------------------+-------------+----------+--------+---------------------------+ +| Warm Isolate, no code cache | 3,489.959us | 44.036us | 1.27% | +22.46% | ++---------------------------------+-------------+----------+--------+---------------------------+ +| Warm Isolate, with code cache | 2,813.156us | 43.351us | 1.53% | 0.00% | ++---------------------------------+-------------+----------+--------+---------------------------+ + +From macOS host +--------------- +4 cores, 16Gb memory + +.. code:: bash + + $ php -v + PHP 7.2.2 (cli) (built: Feb 1 2018 11:50:40) ( NTS ) + Copyright (c) 1997-2018 The PHP Group + Zend Engine v3.2.0, Copyright (c) 1998-2018 Zend Technologies + with Zend OPcache v7.2.2, Copyright (c) 1999-2018, by Zend Technologies + + $ php --ri v8 + V8 support => enabled + Version => v0.2.1-master-dev + Revision => 5d7c3e4 + Compiled => Feb 25 2018 @ 11:42:00 + + V8 Engine Compiled Version => 6.6.313 + V8 Engine Linked Version => 6.6.313 + + + + ++---------------------------------+-------------+-----------+--------+---------------------------+ +| subject | mode | stdev | rstdev | diff (*less is better*) | ++=================================+=============+===========+========+===========================+ +| Cold Isolate, no code cache | 8,732.585us | 97.889us | 1.11% | +6.90% | ++---------------------------------+-------------+-----------+--------+---------------------------+ +| Cold Isolate, with code cache | 8,290.880us | 141.583us | 1.69% | +1.78% | ++---------------------------------+-------------+-----------+--------+---------------------------+ +| Warm Isolate, no code cache | 8,722.684us | 104.547us | 1.19% | +6.68% | ++---------------------------------+-------------+-----------+--------+---------------------------+ +| Warm Isolate, with code cache | 8,194.924us | 70.345us | 0.85% | 0.00% | ++---------------------------------+-------------+-----------+--------+---------------------------+ diff --git a/docs/index.rst b/docs/index.rst new file mode 100644 index 0000000..5e28aa6 --- /dev/null +++ b/docs/index.rst @@ -0,0 +1,41 @@ +Welcome to php-v8's documentation! +================================== + +.. include:: getting-started/donate.rst + +About +===== + +`php-v8`_ is a PHP 7.x extension that brings `V8`_ JavaScript engine API to PHP with some abstraction in mind and +provides an accurate native V8 C++ API implementation available from PHP. + +Hello, world! +============= + +.. code:: php + + run($context) + ->value(), PHP_EOL; + +Content +======= + +.. toctree:: + :maxdepth: 2 + + getting-started/index + getting-started/performance-tricks + development/index + +.. _V8: https://developers.google.com/v8/intro +.. _php-v8: https://github.com/pinepain/php-v8 diff --git a/docs/requirements.txt b/docs/requirements.txt new file mode 100644 index 0000000..65d9e97 --- /dev/null +++ b/docs/requirements.txt @@ -0,0 +1,5 @@ +sphinx~=1.7.1 +sphinx-rtd-theme~=0.1.6 +sphinxcontrib-phpdomain~=0.4.1 + +#sphinxcontrib-spelling~=4.1.0 diff --git a/docs/spelling_wordlist.txt b/docs/spelling_wordlist.txt new file mode 100644 index 0000000..e69de29