Add contrib ports (Contrib ports part 2)

.circleci/config.yml

@@ -418,6 +418,7 @@ jobs:
       - checkout
       - pip-install
       - run: tools/maint/update_settings_docs.py --check
+      - run: tools/maint/update_contrib_ports_docs.py --check
       - run: make -C site text
       - run: tools/maint/check_emcc_help_text.py
       - run: make -C site html

embuilder.py

@@ -126,7 +126,8 @@ def get_help():
   return '''
 Available targets:
 
-  build / clear %s
+  build / clear
+        %s
 
 Issuing 'embuilder build ALL' causes each task to be built.
 ''' % '\n        '.join(all_tasks)

site/source/docs/compiling/Building-Projects.rst

@@ -241,15 +241,18 @@ To see a list of all available ports, run ``emcc --show-ports``.
 .. note:: Since emscripten 3.1.54, ``--use-port`` is the preferred syntax to use a port in your project. The legacy syntax (for example ``-sUSE_SDL2``, ``-sUSE_SDL_IMAGE=2``) remains available.
 
 
+Contrib ports
+-------------
+
+Contrib ports are contributed by the wider community and supported on a "best effort" basis. Since they are not run as part of emscripten CI they are not always guaranteed to build or function. See :ref:`Contrib Ports <contrib_ports>` for more information.
+
 Adding more ports
 -----------------
 
-Adding more ports is fairly easy. Basically, the steps are
+With the introduction of contrib ports, adding a new port is fairly easy. Basically, the steps are:
 
  * Make sure the port is open source and has a suitable license.
- * Add it to emscripten-ports on github. The ports maintainers can create the repo and add the relevant developers to a team for that repo, so they have write access.
- * Add a script to handle it under ``tools/ports/`` (see existing code for examples) and use it in ``tools/ports/__init__.py``.
- * Add testing in the test suite.
+ * Read the ``README.md`` file under ``tools/ports/contrib`` which contains more information.
 
 
 Build system issues

site/source/docs/compiling/Contrib-Ports.rst

@@ -0,0 +1,26 @@
+.. _contrib_ports:
+
+========================
+Emscripten Contrib Ports
+========================
+
+Contrib ports are contributed by the wider community and 
+supported on a "best effort" basis. Since they are not run as part 
+of emscripten CI they are not always guaranteed to build or function.
+
+The following is the complete list of the contrib ports that are 
+available in emscripten. In order to use a contrib port you use the 
+``--use-port=<port_name>`` option (:ref:`emcc <emcc-use-port>`).
+
+.. Auto-generated by update_contrib_ports_docs.py. **DO NOT EDIT**
+
+.. _contrib.glfw3:
+
+contrib.glfw3
+=============
+
+This project is an emscripten port of glfw written in C++ for the web/webassembly platform
+
+`Project information <https://github.com/pongasoft/emscripten-glfw>`_
+
+License: Apache 2.0 license

test/other/test_contrib_ports.cpp

@@ -0,0 +1,25 @@
+/*
+ * Copyright 2024 The Emscripten Authors.  All rights reserved.
+ * Emscripten is available under two separate licenses, the MIT license and the
+ * University of Illinois/NCSA Open Source License.  Both these licenses can be
+ * found in the LICENSE file.
+ */
+
+#include <GLFW/glfw3.h>
+#include <GLFW/emscripten_glfw3.h>
+#include <assert.h>
+
+// cpp otherwise it fails to link
+int main() {
+
+  assert(glfwInit() == GLFW_TRUE);
+
+  GLFWwindow* window = glfwCreateWindow(320, 200, "test_glfw3_port", 0, 0);
+  assert(window != 0);
+  // this call ensures that it uses the right port
+  assert(emscripten_glfw_is_window_fullscreen(window) == EM_FALSE);
+  glfwTerminate();
+
+
+  return 0;
+}

test/test_other.py

@@ -2369,6 +2369,11 @@ def test_sdl2_ttf(self):
     self.emcc(test_file('browser/test_sdl2_ttf.c'), args=['-sUSE_SDL=2', '-sUSE_SDL_TTF=2'], output_filename='a.out.js')
     self.emcc(test_file('browser/test_sdl2_ttf.c'), args=['--use-port=sdl2', '--use-port=sdl2_ttf'], output_filename='a.out.js')
 
+  def test_contrib_ports(self):
+    # Verify that contrib ports can be used (using the only contrib port available ATM, but can be replaced
+    # with a different contrib port when there is another one
+    self.emcc(test_file('other/test_contrib_ports.cpp'), ['--use-port=contrib.glfw3'], output_filename='a.out.js')
+
   def test_link_memcpy(self):
     # memcpy can show up *after* optimizations, so after our opportunity to link in libc, so it must be special-cased
     create_file('main.c', r'''

test/test_sanity.py

@@ -527,9 +527,12 @@ def test_emconfig(self):
   def test_emcc_ports(self):
     restore_and_set_up()
 
+    # validating that ports are valid
+    ports.validate_ports()
+
     # listing ports
     out = self.do([EMCC, '--show-ports'])
-    self.assertContained('Available ports:', out)
+    self.assertContained('Available official ports:', out)
     self.assertContained('sdl2', out)
     self.assertContained('sdl2_image', out)
     self.assertContained('sdl2_net', out)

tools/link.py

@@ -2941,6 +2941,8 @@ def run(linker_inputs, options, state, newargs):
     logger.debug('stopping after linking to object file')
     return 0
 
+  phase_calculate_system_libraries(state, linker_arguments, newargs)
+
   js_syms = {}
   if (not settings.SIDE_MODULE or settings.ASYNCIFY) and not shared.SKIP_SUBPROCS:
     js_info = get_js_sym_info()
@@ -2963,8 +2965,6 @@ def add_js_deps(sym):
       settings.ASYNCIFY_IMPORTS_EXCEPT_JS_LIBS = settings.ASYNCIFY_IMPORTS[:]
       settings.ASYNCIFY_IMPORTS += ['*.' + x for x in js_info['asyncFuncs']]
 
-  phase_calculate_system_libraries(state, linker_arguments, newargs)
-
   phase_link(linker_arguments, wasm_target, js_syms)
 
   # Special handling for when the user passed '-Wl,--version'.  In this case the linker

tools/maint/update_contrib_ports_docs.py

@@ -0,0 +1,82 @@
+#!/usr/bin/env python3
+# Copyright 2024 The Emscripten Authors.  All rights reserved.
+# Emscripten is available under two separate licenses, the MIT license and the
+# University of Illinois/NCSA Open Source License.  Both these licenses can be
+# found in the LICENSE file.
+
+"""Generate the documentation for contrib ports. After adding/updating
+a contrib port, this tool must be re-run.
+"""
+
+import os
+import sys
+import subprocess
+
+script_dir = os.path.dirname(os.path.abspath(__file__))
+root_dir = os.path.dirname(os.path.dirname(script_dir))
+
+sys.path.append(root_dir)
+
+from tools.utils import path_from_root, read_file, safe_ensure_dirs
+from tools import ports
+
+header = '''\
+.. _contrib_ports:
+
+========================
+Emscripten Contrib Ports
+========================
+
+Contrib ports are contributed by the wider community and 
+supported on a "best effort" basis. Since they are not run as part 
+of emscripten CI they are not always guaranteed to build or function.
+
+The following is the complete list of the contrib ports that are 
+available in emscripten. In order to use a contrib port you use the 
+``--use-port=<port_name>`` option (:ref:`emcc <emcc-use-port>`).
+
+.. Auto-generated by update_contrib_ports_docs.py. **DO NOT EDIT**
+'''
+
+
+output_file = path_from_root('site/source/docs/compiling/Contrib-Ports.rst')
+
+
+def write_contrib_port(f, port):
+  heading = port.name
+  f.write('\n.. _' + heading.lower() + ':\n')
+  f.write('\n' + heading + '\n')
+  f.write('=' * len(heading) + '\n\n')
+  f.write(port.project_description())
+  f.write(f'\n\n`Project information <{port.project_url()}>`_')
+  f.write(f'\n\nLicense: {port.project_license()}')
+
+
+def write_contrib_ports(f):
+  for port in sorted(ports.ports, key=lambda p: p.name):
+    if port.is_contrib:
+      write_contrib_port(f, port)
+
+def write_file(f):
+  f.write(header)
+  write_contrib_ports(f)
+
+def main(args):
+  if '--check' in args:
+    safe_ensure_dirs(path_from_root('out'))
+    tmp_output = path_from_root('out/Contrib-Ports.rst')
+    with open(tmp_output, 'w') as f:
+      write_file(f)
+    if read_file(tmp_output) != read_file(output_file):
+      print(f'{output_file} is out-of-date.  Please run tools/maint/update_contrib_ports_docs.py')
+      subprocess.call(['diff', '-u', output_file, tmp_output])
+      return 1
+  else:
+    with open(output_file, 'w') as f:
+      write_file(f)
+
+  return 0
+
+
+if __name__ == '__main__':
+  sys.exit(main(sys.argv[1:]))

tools/ports/__init__.py

@@ -34,13 +34,11 @@
 
 
 def load_port(name):
-  expected_attrs = ['get', 'clear', 'show']
-  port = __import__(name, globals(), level=1)
+  port = __import__(name, globals(), level=1, fromlist=[None])
   ports.append(port)
+  port.is_contrib = name.startswith('contrib.')
   port.name = name
   ports_by_name[port.name] = port
-  for a in expected_attrs:
-    assert hasattr(port, a), 'port %s is missing %s' % (port, a)
   if not hasattr(port, 'needed'):
     port.needed = lambda s: name in ports_needed
   else:
@@ -57,13 +55,32 @@ def load_port(name):
   if not hasattr(port, 'variants'):
     # port variants (default: no variants)
     port.variants = {}
+  if not hasattr(port, 'show') and port.is_contrib:
+    port.show = lambda: f'{port.name} (--use-port={port.name}; {port.project_license()})'
 
   for variant, extra_settings in port.variants.items():
     if variant in port_variants:
       utils.exit_with_error('duplicate port variant: %s' % variant)
     port_variants[variant] = (port.name, extra_settings)
 
 
+def validate_port(port):
+  expected_attrs = ['get', 'clear', 'show']
+  if port.is_contrib:
+    expected_attrs += ['project_url', 'project_description', 'project_license']
+  for a in expected_attrs:
+    assert hasattr(port, a), 'port %s is missing %s' % (port, a)
+
+
+# Called from test_sanity
+def validate_ports():
+  for port in ports:
+    validate_port(port)
+    for dep in port.deps:
+      if dep not in ports_by_name:
+        utils.exit_with_error('unknown dependency in port: %s' % dep)
+
+
 @ToolchainProfiler.profile()
 def read_ports():
   for filename in os.listdir(ports_dir):
@@ -72,10 +89,12 @@ def read_ports():
     filename = os.path.splitext(filename)[0]
     load_port(filename)
 
-  for port in ports:
-    for dep in port.deps:
-      if dep not in ports_by_name:
-        utils.exit_with_error('unknown dependency in port: %s' % dep)
+  contrib_dir = os.path.join(ports_dir, 'contrib')
+  for filename in os.listdir(contrib_dir):
+    if not filename.endswith('.py') or filename == '__init__.py':
+      continue
+    filename = os.path.splitext(filename)[0]
+    load_port('contrib.' + filename)
 
 
 def get_all_files_under(dirname):
@@ -441,9 +460,15 @@ def add_cflags(args, settings): # noqa: U100
 
 
 def show_ports():
-  print('Available ports:')
-  for port in sorted(ports, key=lambda p: p.name):
-    print('   ', port.show())
+  sorted_ports = sorted(ports, key=lambda p: p.name)
+  print('Available official ports:')
+  for port in sorted_ports:
+    if not port.is_contrib:
+      print('   ', port.show())
+  print('Available contrib ports:')
+  for port in sorted_ports:
+    if port.is_contrib:
+      print('   ', port.show())
 
 
 read_ports()

tools/ports/contrib/README.md

@@ -0,0 +1,20 @@
+Emscripten "Contrib" Ports
+==========================
+
+Ports in this directory are contributed by the wider community and are
+supported on a "best effort" basis.  Since they are not run as part of
+emscripten CI they are not always guaranteed to build or function.
+
+If you want to add a contrib port, please use another contrib port as 
+an example. In particular, each contrib port must provide 3 extra piece
+of information (provided as functions in the port file):
+
+* `project_url`: the url where the user can find more information about 
+  the project/port
+* `project_description`: a (short) description of what the project/port 
+  is about
+* `project_license`: the license used by the project/port
+
+After adding (resp. modifying) a contrib port, you must run the 
+`./tools/maint/update_contrib_port_docs.py` command to add (resp. update) 
+the new port to the documentation.

tools/ports/contrib/glfw3.py

@@ -0,0 +1,61 @@
+# Copyright 2024 The Emscripten Authors.  All rights reserved.
+# Emscripten is available under two separate licenses, the MIT license and the
+# University of Illinois/NCSA Open Source License.  Both these licenses can be
+# found in the LICENSE file.
+
+import os
+
+TAG = '1.0.4'
+HASH = 'c3c96718e5d2b37df434a46c4a93ddfd9a768330d33f0d6ce2d08c139752894c2421cdd0fefb800fe41fafc2bbe58c8f22b8aa2849dc4fc6dde686037215cfad'
+
+# name is set when the port is read
+name = ''
+
+
+def get_lib_name(settings):
+  return f'lib_{name}.a'
+
+
+def get(ports, settings, shared):
+  # get the port
+  ports.fetch_project(name, f'https://github.com/pongasoft/emscripten-glfw/releases/download/v{TAG}/emscripten-glfw3-{TAG}.zip', sha512hash=HASH)
+
+  def create(final):
+    root_path = os.path.join(ports.get_dir(), name)
+    source_path = os.path.join(root_path, 'src', 'cpp')
+    source_include_paths = [os.path.join(root_path, 'external', 'GLFW'), os.path.join(root_path, 'include', 'GLFW')]
+    for source_include_path in source_include_paths:
+      ports.install_headers(source_include_path, target='GLFW')
+
+    # this should be an option but better to disable for now...
+    flags = ['-DEMSCRIPTEN_GLFW3_DISABLE_WARNING']
+
+    ports.build_port(source_path, final, name, includes=source_include_paths, flags=flags)
+
+  return [shared.cache.get_lib(get_lib_name(settings), create, what='port')]
+
+
+def clear(ports, settings, shared):
+  shared.cache.erase_lib(get_lib_name(settings))
+
+
+def linker_setup(ports, settings):
+  root_path = os.path.join(ports.get_dir(), name)
+  source_js_path = os.path.join(root_path, 'src', 'js', 'lib_emscripten_glfw3.js')
+  settings.JS_LIBRARIES += [source_js_path]
+
+
+def process_args(ports):
+  return ['-isystem', ports.get_include_dir(name)]
+
+
+def project_url():
+  return 'https://github.com/pongasoft/emscripten-glfw'
+
+
+def project_description():
+  return 'This project is an emscripten port of glfw written in C++ for the web/webassembly platform'
+
+
+def project_license():
+  return 'Apache 2.0 license'