.. Licensed to the Apache Software Foundation (ASF) under one
.. or more contributor license agreements.  See the NOTICE file
.. distributed with this work for additional information
.. regarding copyright ownership.  The ASF licenses this file
.. to you under the Apache License, Version 2.0 (the
.. "License"); you may not use this file except in compliance
.. with the License.  You may obtain a copy of the License at

..   http://www.apache.org/licenses/LICENSE-2.0

.. Unless required by applicable law or agreed to in writing,
.. software distributed under the License is distributed on an
.. "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
.. KIND, either express or implied.  See the License for the
.. specific language governing permissions and limitations
.. under the License.


.. highlight:: console

.. _developers-cpp-emscripten:

===============================================
Cross compiling for WebAssembly with Emscripten
===============================================

Prerequisites
-------------
You need CMake and compilers etc. installed as per the normal build instructions. Before building with Emscripten, you also need to install Emscripten and
activate it using the commands below (see https://emscripten.org/docs/getting_started/downloads.html for details).

.. code:: shell

   git clone https://github.com/emscripten-core/emsdk.git
   cd emsdk
   # replace <version> with the desired EMSDK version.
   # e.g. for Pyodide 0.26, you need EMSDK version 3.1.58
   # the versions can be found in the Makefile.envs file in the Pyodide repo:
   # https://github.com/pyodide/pyodide/blob/10b484cfe427e076c929a55dc35cfff01ea8d3bc/Makefile.envs
   ./emsdk install <version>
   ./emsdk activate <version>
   source ./emsdk_env.sh

If you want to build PyArrow for `Pyodide <https://pyodide.org>`_, you
need ``pyodide-build`` installed via ``pip``, and to be running with the
same version of Python that Pyodide is built for, along with the same
versions of emsdk tools.

.. code:: shell

   # install Pyodide build tools.
   # e.g., for version 0.26 of Pyodide, pyodide-build 0.26 and later work
   pip install "pyodide-build>=0.26"

Then build with the ``ninja-release-emscripten`` CMake preset,
like below:

.. code:: shell

   emcmake cmake --preset "ninja-release-emscripten"
   ninja install

This will install a built static library version of ``libarrow`` it into the
Emscripten sysroot cache, meaning you can build things that depend on it
and they will find ``libarrow``.

e.g. if you want to build for Pyodide, run the commands above, and then
go to ``arrow/python`` and run

.. code:: shell

   pyodide build

It should make a wheel targeting the currently enabled version of
Pyodide in the ``dist`` subdirectory.


Manual Build
------------

If you want to manually build for Emscripten, take a look at the
``CMakePresets.json`` file in the ``arrow/cpp`` directory for a list of things
you will need to override. In particular you will need:

#. Build dependencies set to ``BUNDLED``, so it uses properly cross
   compiled build dependencies.

#. ``CMAKE_TOOLCHAIN_FILE`` set by using ``emcmake cmake`` instead of just ``cmake``.

#. You will need to set ``ARROW_ENABLE_THREADING`` to ``OFF`` for builds
   targeting single-threaded Emscripten environments such as Pyodide.

#. ``ARROW_FLIGHT`` and anything else that uses network probably won't
   work.

#. ``ARROW_JEMALLOC`` and ``ARROW_MIMALLOC`` again probably need to be
   ``OFF``

#. ``ARROW_BUILD_STATIC`` set to ``ON`` and ``ARROW_BUILD_SHARED`` set to
   ``OFF`` is most likely to work.