Officially introduce amalgamated builds (jerryscript-project#4416)

Remove redundancy between all-in-one and all-in-one-source builds
by keeping only the second, and adopt the more established term
"amalgamated" build for it. This change includes the following:

- Replace `ENABLE_ALL_IN_ONE` and `ENABLE_ALL_IN_ONE_SOURCE` cmake
  options with `ENABLE_AMALGAM` top-level option.
- Replace `--all-in-one` option of `build.py` helper with
  `--amalgam`.
- Merge the `srcmerger.py` and `srcgenerator.py` tool scripts into
  `amalgam.py` (with improvements).
- Update documentation.

JerryScript-DCO-1.0-Signed-off-by: Akos Kiss [email protected]

Author: akosthekiss

CMakeLists.txt

@@ -59,6 +59,7 @@ set(DOCTESTS                OFF CACHE BOOL "Build doc tests?")
 
 # Optional build settings
 set(BUILD_SHARED_LIBS  OFF CACHE BOOL "Build shared libraries?")
+set(ENABLE_AMALGAM     OFF CACHE BOOL "Enable amalgamated build?")
 set(ENABLE_LTO         ON  CACHE BOOL "Enable LTO build?")
 set(ENABLE_STRIP       ON  CACHE BOOL "Enable stripping all symbols from release binary?")
 
@@ -104,8 +105,10 @@ if(USING_TI)
 endif()
 
 if(USING_MSVC)
+  set(ENABLE_AMALGAM     ON) # FIXME: This should not be needed but right now it is. To be tracked down and followed up.
   set(ENABLE_STRIP       OFF)
 
+  set(ENABLE_AMALGAM_MESSAGE     " (FORCED BY COMPILER)")
   set(ENABLE_STRIP_MESSAGE       " (FORCED BY COMPILER)")
 endif()
 
@@ -121,6 +124,7 @@ message(STATUS "CMAKE_C_COMPILER_ID            " ${CMAKE_C_COMPILER_ID})
 message(STATUS "CMAKE_SYSTEM_NAME              " ${CMAKE_SYSTEM_NAME})
 message(STATUS "CMAKE_SYSTEM_PROCESSOR         " ${CMAKE_SYSTEM_PROCESSOR})
 message(STATUS "BUILD_SHARED_LIBS              " ${BUILD_SHARED_LIBS})
+message(STATUS "ENABLE_AMALGAM                 " ${ENABLE_AMALGAM} ${ENABLE_AMALGAM_MESSAGE})
 message(STATUS "ENABLE_LTO                     " ${ENABLE_LTO} ${ENABLE_LTO_MESSAGE})
 message(STATUS "ENABLE_STRIP                   " ${ENABLE_STRIP} ${ENABLE_STRIP_MESSAGE})
 message(STATUS "JERRY_VERSION                  " ${JERRY_VERSION})
@@ -247,8 +251,8 @@ if(DEFINED EXTERNAL_LINKER_FLAGS)
   jerry_add_link_flags(${EXTERNAL_LINKER_FLAGS})
 endif()
 
-# Used for placeholder to attach single source build targets
-add_custom_target(generate-single-source)
+# Used as placeholder to attach amalgamated build targets to
+add_custom_target(amalgam)
 
 # Jerry's libm
 if(JERRY_MATH)

appveyor.yml

@@ -23,5 +23,5 @@ before_build:
   - if "%PLATFORM%"=="x64" cmake -G"Visual Studio 15 2017 Win64" -Bbuild -H. -DJERRY_DEBUGGER=ON
 build:
   project: build\Jerry.sln
-  parallel: true
+  parallel: false # FIXME: This should not be needed but right now it is: msbuild generates all amalgamated files twice, at the same time in parallel builds, leading to I/O errors.
   verbosity: minimal

docs/01.CONFIGURATION.md

@@ -5,16 +5,19 @@ A configuration option's value can be changed either by providing specific C pre
 This document lists the available configuration options, shows the configuration name for C, CMake, and python, and provides a brief description that explains the effect of the options.
 
 
-### All-in-one build
+### Amalgamated build
 
-Enables the All-in-one build process, which aggregates the contents of each source file, and uses this combined file to compile the JerryScript library.
-This process can provide comparable results to link time optimization, and can be useful when LTO is not available otherwise.
+Enables the amalgamated build process, which aggregates the contents of each source file per library
+(i.e., JerryScript's core, port, and math libraries), and uses these combined files to compile the project.
+This process can provide comparable results to link-time optimization, and can be useful when LTO is not available otherwise.
 
 | Options |                                              |
 |---------|----------------------------------------------|
 | C:      | `<none>`                                     |
-| CMake:  | `-DENABLE_ALL_IN_ONE=ON/OFF`                 |
-| Python: | `--all-in-one=ON/OFF`                        |
+| CMake:  | `-DENABLE_AMALGAM=ON/OFF`                    |
+| Python: | `--amalgam=ON/OFF`                           |
+
+See also: [Amalgamated sources](#amalgamated-sources)
 
 ### Jerry debugger
 
@@ -278,18 +281,20 @@ This option is disabled by default.
 | Python: | `--mem-stress-test=ON/OFF`                   |
 
 
-# Single source build mode
+# Amalgamated sources
 
-There is a special mode to use/"build" JerryScript. That is generating a single C file which can be
-included into projects quickly. To achive this the following command can be executed to create
-a set of files into the `gen_src` directory (Note that the command is executed in the jerryscript root directory
-but can be adapted to run outside of the project root dir):
+The sources of JerryScript can be combined into a handful of files to allow their easy integration
+in other projects. To achieve this, the following command can be executed to create a set of files
+into the `amalgam` directory:
 
 ```sh
-$ python tools/srcgenerator.py --output-dir gen_src --jerry-core --jerry-port-default --jerry-math
+$ python tools/amalgam.py --output-dir amalgam --jerry-core --jerry-port-default --jerry-math
 ```
 
-The command creates the following files in the `gen_src` dir:
+(Note: In the example above, the command is executed from the project's root directory, but that is
+not mandatory.)
+
+The command creates the following files in the `amalgam` dir:
 
 * `jerryscript.c`
 * `jerryscript.h`
@@ -304,15 +309,15 @@ should be adapted to the required use-case. See the file contents for more detai
 default configuration. (Note: This config file is created from the the `jerry-core/config.h` file.)
 
 These files can be directly compiled with an application using the JerryScript API.
-For example with the following command:
+E.g., using a command similar to the one below:
 
 ```sh
-$ gcc -Wall -o demo_app demo_app.c gen_src/jerryscript.c gen_src/jerryscript-port-default.c jerryscript-math.c -Igen_src/
+$ gcc -Wall -o demo_app demo_app.c amalgam/jerryscript.c amalgam/jerryscript-port-default.c amalgam/jerryscript-math.c -Iamalgam/
 ```
 
-Please note that the headers must be available on the include path.
+(Note: The headers must be available on the include path.)
 
-In addition there is a `-DENABLE_ALL_IN_ONE_SOURCE=ON` CMake option to use this kind of sources during the build.
+This approach is also under the hood of the [amalgamated build](#amalgamated-build) process.
 
 # Target specific information
 

jerry-core/CMakeLists.txt

@@ -18,9 +18,6 @@ project (${JERRY_CORE_NAME} C)
 
 include(CheckLibraryExists)
 
-# Optional build settings
-set(ENABLE_ALL_IN_ONE               OFF          CACHE BOOL   "Enable all-in-one build?")
-
 # Optional features
 set(JERRY_CPOINTER_32_BIT           OFF          CACHE BOOL   "Enable 32 bit compressed pointers?")
 set(JERRY_DEBUGGER                  OFF          CACHE BOOL   "Enable JerryScript debugger?")
@@ -46,12 +43,6 @@ set(JERRY_STACK_LIMIT               "(0)"        CACHE STRING "Maximum stack usa
 set(JERRY_GC_MARK_LIMIT             "(8)"        CACHE STRING "Maximum depth of recursion during GC mark phase")
 
 # Option overrides
-if(USING_MSVC)
-  set(ENABLE_ALL_IN_ONE ON) # FIXME: This should not be needed but right now it is. To be tracked down and followed up.
-
-  set(ENABLE_ALL_IN_ONE_MESSAGE " (FORCED BY COMPILER)")
-endif()
-
 if(JERRY_SYSTEM_ALLOCATOR)
   set(JERRY_CPOINTER_32_BIT ON)
 
@@ -85,7 +76,6 @@ if(JERRY_MEM_STATS OR JERRY_PARSER_DUMP_BYTE_CODE OR JERRY_REGEXP_DUMP_BYTE_CODE
 endif()
 
 # Status messages
-message(STATUS "ENABLE_ALL_IN_ONE              " ${ENABLE_ALL_IN_ONE} ${ENABLE_ALL_IN_ONE_MESSAGE})
 message(STATUS "JERRY_CPOINTER_32_BIT          " ${JERRY_CPOINTER_32_BIT} ${JERRY_CPOINTER_32_BIT_MESSAGE})
 message(STATUS "JERRY_DEBUGGER                 " ${JERRY_DEBUGGER})
 message(STATUS "JERRY_ERROR_MESSAGES           " ${JERRY_ERROR_MESSAGES})
@@ -147,55 +137,41 @@ file(GLOB SOURCE_CORE_FILES
      parser/regexp/*.c
      vm/*.c)
 
-# All-in-one build
-if(ENABLE_ALL_IN_ONE)
-  set(ALL_IN_FILE "${CMAKE_BINARY_DIR}/jerry-all-in.c")
-  list(SORT SOURCE_CORE_FILES)
-  file(REMOVE ${ALL_IN_FILE})
-
-  foreach(FILE ${SOURCE_CORE_FILES})
-    file(APPEND ${ALL_IN_FILE} "#include \"${FILE}\"\n")
-  endforeach()
-
-  set(SOURCE_CORE_FILES ${ALL_IN_FILE})
-endif()
-
-# "Single" JerryScript source/header build.
+# Amalgamated JerryScript source/header build.
 #  The process will create the following files:
 #   * jerryscript.c
 #   * jerryscript.h
 #   * jerryscript-config.h
-if(ENABLE_ALL_IN_ONE_SOURCE)
+if(ENABLE_AMALGAM)
 
   # Create single C/H file
   file(GLOB HEADER_CORE_FILES *.h)
 
   # Generated files
-  set(ALL_IN_FILE "${CMAKE_BINARY_DIR}/src/jerryscript.c")
-  set(ALL_IN_FILE_H "${CMAKE_BINARY_DIR}/src/jerryscript.h")
-  set(JERRYSCRIPT_CONFIG_H "${CMAKE_BINARY_DIR}/src/jerryscript-config.h")
+  set(AMALGAM_CORE_C "${CMAKE_BINARY_DIR}/amalgam/jerryscript.c")
+  set(AMALGAM_CORE_H "${CMAKE_BINARY_DIR}/amalgam/jerryscript.h")
+  set(AMALGAM_CONFIG_H "${CMAKE_BINARY_DIR}/amalgam/jerryscript-config.h")
 
-  add_custom_command(OUTPUT ${ALL_IN_FILE} ${ALL_IN_FILE_H}
-                     COMMAND python ${CMAKE_SOURCE_DIR}/tools/srcgenerator.py
+  add_custom_command(OUTPUT ${AMALGAM_CORE_C} ${AMALGAM_CORE_H}
+                     COMMAND python ${CMAKE_SOURCE_DIR}/tools/amalgam.py
                              --jerry-core
-                             --output-dir ${CMAKE_BINARY_DIR}/src
+                             --output-dir ${CMAKE_BINARY_DIR}/amalgam
                      DEPENDS ${SOURCE_CORE_FILES}
                              ${HEADER_CORE_FILES}
-                             ${CMAKE_SOURCE_DIR}/tools/srcgenerator.py
-                             ${CMAKE_SOURCE_DIR}/tools/srcmerger.py
+                             ${CMAKE_SOURCE_DIR}/tools/amalgam.py
   )
 
   # The "true" jerryscript-config.h will be generated by the configure_file below,
   # which contains the default options and the ones passed for the CMake.
   # The input for this is the jerryscript-config.h generated by the command above.
   set(JERRYSCRIPT_GEN_CONFIG_H ${CMAKE_CURRENT_BINARY_DIR}/jerryscript-config.h)
-  add_custom_command(OUTPUT ${JERRYSCRIPT_CONFIG_H}
-                     COMMAND ${CMAKE_COMMAND} -E copy ${JERRYSCRIPT_GEN_CONFIG_H} ${JERRYSCRIPT_CONFIG_H}
-                     DEPENDS ${ALL_IN_FILE_C} ${ALL_IN_FILE_H})
-  add_custom_target(generate-single-source-jerry DEPENDS ${ALL_IN_FILE} ${ALL_IN_FILE_H})
-  add_dependencies(generate-single-source generate-single-source-jerry)
+  add_custom_command(OUTPUT ${AMALGAM_CONFIG_H}
+                     COMMAND ${CMAKE_COMMAND} -E copy ${JERRYSCRIPT_GEN_CONFIG_H} ${AMALGAM_CONFIG_H}
+                     DEPENDS ${AMALGAM_CORE_C} ${AMALGAM_CORE_H})
+  add_custom_target(amalgam-jerry DEPENDS ${AMALGAM_CORE_C} ${AMALGAM_CORE_H} ${AMALGAM_CONFIG_H})
+  add_dependencies(amalgam amalgam-jerry)
 
-  set(SOURCE_CORE_FILES ${ALL_IN_FILE} ${ALL_IN_FILE_H} ${JERRYSCRIPT_CONFIG_H})
+  set(SOURCE_CORE_FILES ${AMALGAM_CORE_C} ${AMALGAM_CORE_H} ${AMALGAM_CONFIG_H})
 endif()
 
 # Third-party

jerry-math/CMakeLists.txt

@@ -30,28 +30,27 @@ set(INCLUDE_MATH "${CMAKE_CURRENT_SOURCE_DIR}/include")
 # Source directories
 file(GLOB SOURCE_MATH *.c)
 
-# "Single" JerryScript libm source/header build.
+# Amalgamated JerryScript source/header build.
 #  The process will create the following files:
 #   * jerryscript-math.c
 #   * math.h
-if(ENABLE_ALL_IN_ONE_SOURCE)
+if(ENABLE_AMALGAM)
   file(GLOB HEADER_MATH *.h)
-  set(ALL_IN_FILE "${CMAKE_BINARY_DIR}/src/jerryscript-math.c")
-  set(ALL_IN_FILE_H "${CMAKE_BINARY_DIR}/src/math.h")
+  set(AMALGAM_MATH_C "${CMAKE_BINARY_DIR}/amalgam/jerryscript-math.c")
+  set(AMALGAM_MATH_H "${CMAKE_BINARY_DIR}/amalgam/math.h")
 
-  add_custom_command(OUTPUT ${ALL_IN_FILE} ${ALL_IN_FILE_H} ${JERRYSCRIPT_CONFIG_H}
-                     COMMAND python ${CMAKE_SOURCE_DIR}/tools/srcgenerator.py
+  add_custom_command(OUTPUT ${AMALGAM_MATH_C} ${AMALGAM_MATH_H}
+                     COMMAND python ${CMAKE_SOURCE_DIR}/tools/amalgam.py
                              --jerry-math
-                             --output-dir ${CMAKE_BINARY_DIR}/src
+                             --output-dir ${CMAKE_BINARY_DIR}/amalgam
                      DEPENDS ${SOURCE_MATH}
                              ${HEADER_MATH}
-                             ${CMAKE_SOURCE_DIR}/tools/srcgenerator.py
-                             ${CMAKE_SOURCE_DIR}/tools/srcmerger.py
+                             ${CMAKE_SOURCE_DIR}/tools/amalgam.py
   )
-  add_custom_target(generate-single-source-math DEPENDS ${ALL_IN_FILE} ${ALL_IN_FILE_H})
-  add_dependencies(generate-single-source generate-single-source-math)
+  add_custom_target(amalgam-math DEPENDS ${AMALGAM_MATH_C} ${AMALGAM_MATH_H})
+  add_dependencies(amalgam amalgam-math)
 
-  set(SOURCE_MATH ${ALL_IN_FILE} ${ALL_IN_FILE_H})
+  set(SOURCE_MATH ${AMALGAM_MATH_C} ${AMALGAM_MATH_H})
 endif()
 
 add_library(${JERRY_MATH_NAME} ${SOURCE_MATH})

jerry-port/default/CMakeLists.txt

@@ -22,28 +22,27 @@ set(INCLUDE_PORT_DEFAULT "${CMAKE_CURRENT_SOURCE_DIR}/include")
 # Source directories
 file(GLOB SOURCE_PORT_DEFAULT *.c)
 
-# "Single" JerryScript source/header build.
+# Amalgamated JerryScript source/header build.
 #  The process will create the following files:
 #   * jerryscript-port-default.c
 #   * jerryscript-port-default.h
-if(ENABLE_ALL_IN_ONE_SOURCE)
+if(ENABLE_AMALGAM)
   file(GLOB HEADER_PORT_DEFAULT *.h)
-  set(ALL_IN_FILE "${CMAKE_BINARY_DIR}/src/jerryscript-port-default.c")
-  set(ALL_IN_FILE_H "${CMAKE_BINARY_DIR}/src/jerryscript-port-default.h")
+  set(AMALGAM_PORT_C "${CMAKE_BINARY_DIR}/amalgam/jerryscript-port-default.c")
+  set(AMALGAM_PORT_H "${CMAKE_BINARY_DIR}/amalgam/jerryscript-port-default.h")
 
-  add_custom_command(OUTPUT ${ALL_IN_FILE} ${ALL_IN_FILE_H} ${JERRYSCRIPT_CONFIG_H}
-                     COMMAND python ${CMAKE_SOURCE_DIR}/tools/srcgenerator.py
+  add_custom_command(OUTPUT ${AMALGAM_PORT_C} ${AMALGAM_PORT_H}
+                     COMMAND python ${CMAKE_SOURCE_DIR}/tools/amalgam.py
                              --jerry-port-default
-                             --output-dir ${CMAKE_BINARY_DIR}/src
+                             --output-dir ${CMAKE_BINARY_DIR}/amalgam
                      DEPENDS ${SOURCE_PORT_DEFAULT}
                              ${HEADER_PORT_DEFAULT}
-                             ${CMAKE_SOURCE_DIR}/tools/srcgenerator.py
-                             ${CMAKE_SOURCE_DIR}/tools/srcmerger.py
+                             ${CMAKE_SOURCE_DIR}/tools/amalgam.py
   )
-  add_custom_target(generate-single-source-port DEPENDS ${ALL_IN_FILE} ${ALL_IN_FILE_H})
-  add_dependencies(generate-single-source generate-single-source-port)
+  add_custom_target(amalgam-port DEPENDS ${AMALGAM_PORT_C} ${AMALGAM_PORT_H})
+  add_dependencies(amalgam amalgam-port)
 
-  set(SOURCE_PORT_DEFAULT ${ALL_IN_FILE} ${ALL_IN_FILE_H})
+  set(SOURCE_PORT_DEFAULT ${AMALGAM_PORT_C} ${AMALGAM_PORT_H})
 endif()
 
 # Define _BSD_SOURCE and _DEFAULT_SOURCE

targets/esp8266/Makefile.esp8266

@@ -49,7 +49,7 @@ jerry:
 	 -DCMAKE_C_COMPILER=xtensa-lx106-elf-gcc \
 	 -DCMAKE_C_COMPILER_WORKS=TRUE \
 	 -DENABLE_LTO=OFF \
-	 -DENABLE_ALL_IN_ONE=ON \
+	 -DENABLE_AMALGAM=ON \
 	 -DJERRY_MATH=ON \
 	 -DJERRY_CMDLINE=OFF \
 	 -DJERRY_PROFILE="es5.1" \

targets/nuttx-stm32f4/Makefile.travis

@@ -51,7 +51,7 @@ install: install-apt-get-deps install-noapt
 
 # Build JerryScript.
 script-build-jerryscript:
-	tools/build.py --clean --toolchain cmake/toolchain_mcu_stm32f4.cmake --profile=es.next --jerry-cmdline OFF --lto OFF --jerry-math ON --all-in-one ON --jerry-port-default OFF --mem-heap 70 --compile-flag='--sysroot=../nuttx'
+	tools/build.py --clean --toolchain cmake/toolchain_mcu_stm32f4.cmake --profile=es.next --jerry-cmdline OFF --lto OFF --jerry-math ON --amalgam ON --jerry-port-default OFF --mem-heap 70 --compile-flag='--sysroot=../nuttx'
 
 # Link in the NuttX JerryScript target directory under the NuttX apps tree.
 script-add-jerryscript-app:

targets/nuttx-stm32f4/README.md

@@ -42,7 +42,7 @@ jerryscript/tools/build.py \
     --lto=OFF \
     --jerry-cmdline=OFF \
     --jerry-math=ON \
-    --all-in-one=ON \
+    --amalgam=ON \
     --mem-heap=70 \
     --profile=es.next \
     --compile-flag="--sysroot=${PWD}/nuttx" \

targets/particle/Makefile.particle

@@ -44,7 +44,6 @@ jerrycore:
 	 -DCMAKE_C_COMPILER=arm-none-eabi-gcc \
 	 -DCMAKE_C_COMPILER_WORKS=TRUE \
 	 -DENABLE_LTO=ON \
-	 -DENABLE_ALL_IN_ONE=OFF \
 	 -DJERRY_CMDLINE=OFF \
 	 -DJERRY_PROFILE=minimal \
 	 -DENABLE_STRIP=OFF \

targets/riot-stm32f4/Makefile.riot

@@ -46,7 +46,6 @@ libjerry:
 	 -DCMAKE_C_COMPILER=$(CC) \
 	 -DCMAKE_C_COMPILER_WORKS=TRUE \
 	 -DENABLE_LTO=OFF \
-	 -DENABLE_ALL_IN_ONE=OFF \
 	 -DJERRY_CMDLINE=OFF \
 	 -DJERRY_PROFILE="es5.1" \
 	 -DEXTERNAL_COMPILE_FLAGS="$(EXT_CFLAGS)" \

targets/zephyr/Makefile.zephyr

@@ -82,7 +82,6 @@ endif
 	 -DCMAKE_C_COMPILER="$(subst ccache ,,$(CC))" \
 	 -DCMAKE_C_COMPILER_WORKS=TRUE \
 	 -DENABLE_LTO=OFF \
-	 -DENABLE_ALL_IN_ONE=OFF \
 	 -DJERRY_CMDLINE=OFF \
 	 -DJERRY_PROFILE=$(JERRYPROFILE) \
 	 -DJERRY_ERROR_MESSAGES=ON \