.. _packaging-files: =============== Packaging Files =============== This topic shows how to package the files that will be used to populate :ref:`Emscripten's virtual file system ` when the page is loaded. There are two alternatives for how files are packaged: *preloading* and *embedding*. Embedding puts the specified files inside the generated JavaScript, while preloading packages the files separately. Embedding files is much less efficient than preloading and should only be used when packaging small numbers of small files. Preloading also enables the option to separately host the data. *Emcc* uses the *file packager* to package the files and generate the :ref:`File System API ` calls that create and load the file system at run time. While *Emcc* is the recommended tool for packaging, there are cases where it can make sense to run the *file packager* manually. With ``--use-preload-plugins``, files can be automatically decoded based on their extension. See :ref:`preloading-files` for more information. Packaging using emcc ==================== The easiest way to package files is to use :ref:`emcc ` at compile time. The :ref:`preload ` and :ref:`embed ` commands select their respective packaging methods. The command below shows how to package files for preloading: .. code-block:: bash emcc file.cpp -o file.html --preload-file asset_dir The command generates **file.html**, **file.js** and **file.data**. The **.data** file contains all the files in **asset_dir/**, and is loaded by **file.js**. .. note:: The :ref:`Tutorial ` demonstrates preloading using the **hello_world_file.cpp** test code. The command for embedding is shown below. In this case *emcc* generates **file.html** and **file.js** — the contents of **asset_dir/** are embedded directly into the **file.js**: .. code-block:: bash emcc file.cpp -o file.html --embed-file asset_dir By default, the files to be packaged should be nested in or below the compile-time command prompt directory. At runtime the same nested file structure is mapped to the virtual file system, with the root corresponding to the command prompt directory. For example, consider a file structure **dir1/dir2/dir3/asset_dir/** where the project is compiled from **dir2**. When we package **asset_dir**, we specify its relative location **dir3/asset_dir/**: .. code-block:: bash emcc file.cpp -o file.html --preload-file dir3/asset_dir The folder is available at this same location **dir3/asset_dir** in the virtual file system at runtime. Similarly, if we packaged a file in *dir2*, it would be available in the root of the virtual file system at runtime. The ``@`` symbol can be used to map packaged files from any location in the local file system to any location in the virtual file system. This is discussed below in :ref:`packaging-files-packaged-file-location`. .. _packaging-files-file-packager: Packaging using the file packager tool ====================================== You can also run the *file packager* manually using the instructions at the top of `file_packager.py `_. The file packager generates a **.data** file and **.js** file. The **.js** file contains the code to use the data file, and must be loaded *before* loading your main compiled code. (For instance, add ``