README.rst - external/naclports - Git at Google

 naclports - Ports of open source software to Native Client
 ==========================================================

 naclports is collection of open source libraries and applications that have
 been ported to Native Client, along with set to tools for building and
 maintaining them.

 Packages can be built from source or prebuilt binaries packages can be
 downloaded from the continuous build system.

 The sources for the ports live in the ``ports`` directory.  Each one contains
 at least the following file:

 - pkg_info: a description of the package.

 Most also contain the follow optional files:

 - build.sh: a bash script for building it
 - nacl.patch: an optional patch file.

 The tools for building packages live in ``bin``.  The binary tool is simple
 called ``naclports``.  To build and install a package into the toolchain run
 ``naclports install <package_dir>``.  This script will download, patch, build
 and install the application or library.  By default it will first install any
 dependencies that that the package has.


 Links
 -----

 Project home: https://code.google.com/p/naclports/
 Continuous builder: http://build.chromium.org/p/client.nacl.ports/
 Continuous build artifacts: http://gsdview.appspot.com/naclports/builds/


 Prerequistes
 ------------

 The minimum requirements for using naclports are:

 - python 2.7
 - Native Client SDK

 For building packages from source the build scripts require that certain tools
 are present in the host system:

 - bash
 - make
 - curl
 - sed
 - git

 To build all ports you will also need these:

 - cmake
 - texinfo
 - gettext
 - pkg-config
 - autoconf, automake, libtool
 - libglib2.0-dev >= 2.26.0 (if you want to build glib)
 - xsltproc

 To ensure you have all required packages you can run the
 install-build-deps.sh from the chromium repo.

 On Mac OS X you can use homebrew to install these using the following command::

   brew install autoconf automake cmake gettext libtool pkg-config

 The build system for some of the native Python modules relies on a 32-bit
 host build of Python itself, which in turn relies on the development version
 of zlib and libssl being available.  On 64-bit Ubuntu/Trust this means
 installing:

 - zlib1g-dev:i386
 - libssl-dev:i386

 On older Debian/Ubuntu systems the packages were called:

 - lib32z1-dev
 - libssl0.9.8:i


 Building
 --------

 Before you can build any of the package you must set the ``NACL_SDK_ROOT``
 environment variable to top directory of a version of the Native Client SDK
 (the directory containing toolchain/). This path should be absolute.

 The top level Makefile can be used as a quick way to build one or more
 packages. For example, ``make libvorbis`` will build ``libvorbis`` and
 ``libogg``. ``make all`` will build all the packages.

 There are 4 possible architectures that NaCl modules can be compiled for: i686,
 x86_64, arm, pnacl. The naclports build system will only build just one at at
 time. You can control which one by setting the ``NACL_ARCH`` environment
 variable. e.g.::

   $ NACL_ARCH=arm make openssl

 For some architectures there is more than one toolchain available.  For example
 for x86 you can choose between newlib and glibc.  The toolchain defaults to
 newlib and can be specified by setting the ``TOOLCHAIN`` environment variable::

   $ NACL_ARCH=i686 TOOLCHAIN=glibc make openssl

 If you want to build a certain package for all architectures and all toolchains
 you can use the top level ``make_all.sh`` script. e.g.::

   $ ./make_all.sh openssl

 Headers and libraries are installed into the toolchains directly so there is
 not add extra -I or -L options in order to use the libraries.

 The source code and build output for each package is placed in::

   out/build/<PACKAGE_NAME>

 By default all builds are in release configuration.  If you want to build
 debug packages set ``NACL_DEBUG=1`` or pass ``--debug`` to the naclports
 script.

 **Note**: Each package has its own license. Please read and understand these
 licenses before using these packages in your projects.

 **Note to Windows users**: These scripts are written in bash and must be
 launched from a Cygwin shell. While many of the scripts should work under
 Cygwin naclports is only tested on Linux and Mac so YMMV.


 Binary Packages
 ---------------

 By default naclports will attempt to install binary packages rather than
 building them from source. The binary packages are produced by the buildbots
 and stored in Google cloud storage. The index of current binary packages
 is stored in ``lib/prebuilt.txt`` and this is currently manually updated
 by running ``build_tools/scan_packages.py``.

 If the package version does not match the package will always be built from
 source.

 If you want to force a package to be built from source you can pass
 ``--from-source`` to the naclports script.


 Running the examples
 --------------------

 Applications/Examples that build runnable web pages are published to
 ``out/publish``. To run them in chrome you need to serve them with a web
 server.  The easiest way to do this is to run::

   $ make run

 This will start a local web server serving the content of ``out/publish``
 after which you can navigate to http://localhost:5103 to view the content.


 Adding a new package
 --------------------

 To add a package:

 1. If you are using svn, make sure you have a writable version of the
    repository::

      $ gclient config https://naclports.googlecode.com/svn/trunk/src

 2. Add a directory to the ``ports`` directory using the name your new package.
    For example: ``ports/openssl``.
 3. Add the build.sh script and pkg_info to that directory.
 4. Optionally include the upstream tarball and add its sha1 checksum to
    pkg_info. You can do this using ``build_tools/sha1sum.py``.  Redirect the
    script to append to the pkg_info file.  e.g.::

      $ sha1sum.py mypkg.tar.gz >> ports/openssl/pkg_info

 5. Optionally include a patch file (nacl.patch). See below for the
    recommended way to generate this patch.
 6. Make sure your package builds for all architectures::

      $ ./make_all.sh <PACKAGE_NAME>


 Writing build scripts
 ---------------------

 Each port has an optional build script: ``build.sh``. Some ports, such as
 those that are based on autotools+make don't need a build script at all. The
 build script is run in a bash shell, it can set variables at the global scope
 that override the default behaviour of various steps in the build process. The
 most common steps that implement by package-specific scripts are:

 - ConfigureStep()
 - BuildStep()
 - InstallStep()
 - TestStep()

 When implementing a given step the default step can be still invoked, e.g.
 by calling DefaultBuildStep() from within BuildStep()

 Each build is is run independently in a subshell, so variables set in one
 step are not visible in others, and changing the working directory within a
 step will not effect other steps.

 A variety of shared variables and functions are available from with the build
 scripts.  These are defined in build_tools/common.sh.

 When modifying any shell scripts in naclports it is recommended that you
 run ``shellcheck`` to catch common errors.  The recommended command line
 for this is::

   shellcheck -e SC2044,SC2129,SC2046,SC2035,SC2034,SC2086,SC2148 \
     `git ls-files "*.sh"`

 Modifying package sources / Working with patches
 ------------------------------------------------

 When a package is first built, its source is downloaded and extracted to
 ``out/build/<PKG_NAME>``. A new git repository is then created in this
 folder with the original archive contents on a branch called ``upstream``. The
 optional ``nacl.patch`` file is then applied on the ``master`` branch. This
 means that at any given time you can see the changes from upstream using ``git
 diff upstream``.

 To make changes to a package's patch file the recommended workflow is:

 1. Directly modify the sources in ``out/build/PKG_NAME``.
 2. Build the package and verify the changes.
 3. Use ``git diff upstream.. > ../path/to/nacl.patch`` to regenerate
    the patch file.

 Whenever the upstream archive or patch file changes and you try to build the
 package you will be prompted to remove the existing repository and start a new
 one. This is to avoid deleting a repository that might have unsaved changed.

 Happy porting!
	naclports - Ports of open source software to Native Client
	==========================================================

	naclports is collection of open source libraries and applications that have
	been ported to Native Client, along with set to tools for building and
	maintaining them.

	Packages can be built from source or prebuilt binaries packages can be
	downloaded from the continuous build system.

	The sources for the ports live in the ``ports`` directory. Each one contains
	at least the following file:

	- pkg_info: a description of the package.

	Most also contain the follow optional files:

	- build.sh: a bash script for building it
	- nacl.patch: an optional patch file.

	The tools for building packages live in ``bin``. The binary tool is simple
	called ``naclports``. To build and install a package into the toolchain run
	``naclports install <package_dir>``. This script will download, patch, build
	and install the application or library. By default it will first install any
	dependencies that that the package has.


	Links
	-----

	Project home: https://code.google.com/p/naclports/
	Continuous builder: http://build.chromium.org/p/client.nacl.ports/
	Continuous build artifacts: http://gsdview.appspot.com/naclports/builds/


	Prerequistes
	------------

	The minimum requirements for using naclports are:

	- python 2.7
	- Native Client SDK

	For building packages from source the build scripts require that certain tools
	are present in the host system:

	- bash
	- make
	- curl
	- sed
	- git

	To build all ports you will also need these:

	- cmake
	- texinfo
	- gettext
	- pkg-config
	- autoconf, automake, libtool
	- libglib2.0-dev >= 2.26.0 (if you want to build glib)
	- xsltproc

	To ensure you have all required packages you can run the
	install-build-deps.sh from the chromium repo.

	On Mac OS X you can use homebrew to install these using the following command::

	brew install autoconf automake cmake gettext libtool pkg-config

	The build system for some of the native Python modules relies on a 32-bit
	host build of Python itself, which in turn relies on the development version
	of zlib and libssl being available. On 64-bit Ubuntu/Trust this means
	installing:

	- zlib1g-dev:i386
	- libssl-dev:i386

	On older Debian/Ubuntu systems the packages were called:

	- lib32z1-dev
	- libssl0.9.8:i


	Building
	--------

	Before you can build any of the package you must set the ``NACL_SDK_ROOT``
	environment variable to top directory of a version of the Native Client SDK
	(the directory containing toolchain/). This path should be absolute.

	The top level Makefile can be used as a quick way to build one or more
	packages. For example, ``make libvorbis`` will build ``libvorbis`` and
	``libogg``. ``make all`` will build all the packages.

	There are 4 possible architectures that NaCl modules can be compiled for: i686,
	x86_64, arm, pnacl. The naclports build system will only build just one at at
	time. You can control which one by setting the ``NACL_ARCH`` environment
	variable. e.g.::

	$ NACL_ARCH=arm make openssl

	For some architectures there is more than one toolchain available. For example
	for x86 you can choose between newlib and glibc. The toolchain defaults to
	newlib and can be specified by setting the ``TOOLCHAIN`` environment variable::

	$ NACL_ARCH=i686 TOOLCHAIN=glibc make openssl

	If you want to build a certain package for all architectures and all toolchains
	you can use the top level ``make_all.sh`` script. e.g.::

	$ ./make_all.sh openssl

	Headers and libraries are installed into the toolchains directly so there is
	not add extra -I or -L options in order to use the libraries.

	The source code and build output for each package is placed in::

	out/build/<PACKAGE_NAME>

	By default all builds are in release configuration. If you want to build
	debug packages set ``NACL_DEBUG=1`` or pass ``--debug`` to the naclports
	script.

	Note: Each package has its own license. Please read and understand these
	licenses before using these packages in your projects.

	Note to Windows users: These scripts are written in bash and must be
	launched from a Cygwin shell. While many of the scripts should work under
	Cygwin naclports is only tested on Linux and Mac so YMMV.


	Binary Packages
	---------------

	By default naclports will attempt to install binary packages rather than
	building them from source. The binary packages are produced by the buildbots
	and stored in Google cloud storage. The index of current binary packages
	is stored in ``lib/prebuilt.txt`` and this is currently manually updated
	by running ``build_tools/scan_packages.py``.

	If the package version does not match the package will always be built from
	source.

	If you want to force a package to be built from source you can pass
	``--from-source`` to the naclports script.


	Running the examples
	--------------------

	Applications/Examples that build runnable web pages are published to
	``out/publish``. To run them in chrome you need to serve them with a web
	server. The easiest way to do this is to run::

	$ make run

	This will start a local web server serving the content of ``out/publish``
	after which you can navigate to http://localhost:5103 to view the content.


	Adding a new package
	--------------------

	To add a package:

	1. If you are using svn, make sure you have a writable version of the
	repository::

	$ gclient config https://naclports.googlecode.com/svn/trunk/src

	2. Add a directory to the ``ports`` directory using the name your new package.
	For example: ``ports/openssl``.
	3. Add the build.sh script and pkg_info to that directory.
	4. Optionally include the upstream tarball and add its sha1 checksum to
	pkg_info. You can do this using ``build_tools/sha1sum.py``. Redirect the
	script to append to the pkg_info file. e.g.::

	$ sha1sum.py mypkg.tar.gz >> ports/openssl/pkg_info

	5. Optionally include a patch file (nacl.patch). See below for the
	recommended way to generate this patch.
	6. Make sure your package builds for all architectures::

	$ ./make_all.sh <PACKAGE_NAME>


	Writing build scripts
	---------------------

	Each port has an optional build script: ``build.sh``. Some ports, such as
	those that are based on autotools+make don't need a build script at all. The
	build script is run in a bash shell, it can set variables at the global scope
	that override the default behaviour of various steps in the build process. The
	most common steps that implement by package-specific scripts are:

	- ConfigureStep()
	- BuildStep()
	- InstallStep()
	- TestStep()

	When implementing a given step the default step can be still invoked, e.g.
	by calling DefaultBuildStep() from within BuildStep()

	Each build is is run independently in a subshell, so variables set in one
	step are not visible in others, and changing the working directory within a
	step will not effect other steps.

	A variety of shared variables and functions are available from with the build
	scripts. These are defined in build_tools/common.sh.

	When modifying any shell scripts in naclports it is recommended that you
	run ``shellcheck`` to catch common errors. The recommended command line
	for this is::

	shellcheck -e SC2044,SC2129,SC2046,SC2035,SC2034,SC2086,SC2148 \
	`git ls-files "*.sh"`

	Modifying package sources / Working with patches
	------------------------------------------------

	When a package is first built, its source is downloaded and extracted to
	``out/build/<PKG_NAME>``. A new git repository is then created in this
	folder with the original archive contents on a branch called ``upstream``. The
	optional ``nacl.patch`` file is then applied on the ``master`` branch. This
	means that at any given time you can see the changes from upstream using ``git
	diff upstream``.

	To make changes to a package's patch file the recommended workflow is:

	1. Directly modify the sources in ``out/build/PKG_NAME``.
	2. Build the package and verify the changes.
	3. Use ``git diff upstream.. > ../path/to/nacl.patch`` to regenerate
	the patch file.

	Whenever the upstream archive or patch file changes and you try to build the
	package you will be prompted to remove the existing repository and start a new
	one. This is to avoid deleting a repository that might have unsaved changed.

	Happy porting!