Skip to content

Latest commit

 

History

History
147 lines (110 loc) · 10.9 KB

CONTRIBUTING.md

File metadata and controls

147 lines (110 loc) · 10.9 KB
Raw

Contribution Guide Overview

This guide provides steps on how to make contributions, report bugs, and become a part of the ongoing development of Socket Runtime. If you are new to Socket Runtime, the Guides is a good place to start.

Requirements

To contribute to the project you need to clone the repository and install the dependencies.

MacOS and Linux

git clone git@github.com:socketsupply/socket.git
cd socket
./bin/install.sh

Windows

git clone git@github.com:socketsupply/socket.git
cd socket
.\bin\install.ps1

Building ssc and other useful commands

ssc (short for Socket Supply Compiler) is a command-line tool that is used to build Socket Runtime applications. It is a wrapper around the native build tools for each platform and provides a unified interface for building Socket Runtime applications. You don't have to use Xcode, MSAndroid Studio, or Visual Studio to build Socket Runtime applications, but you can if you want to.

./bin/install.sh (macOS and Linux) or .\bin\install.ps1 (Windows)

This command installs the dependencies for Socket Runtime and builds ssc for your platform.

  • ssc on macOS can cross-compile for iOS, iOS Simulator, Android, and Android Emulator.
  • ssc on Linux can cross-compile for Android and Android Emulator.
  • ssc on Windows can cross-compile for Android and Android Emulator.

Additional flags on macOS and Linux:

  • VERBOSE=1 - prints useful information about the build process. Please use this flag if you are reporting a bug.
  • DEBUG=1 - builds ssc in debug mode. This is useful if you are developing ssc and want to debug it.
  • NO_ANDROID=1 - skips the ssc's Android support. This is useful if you are not developing for Android and don't want to install the Android SDK.
  • NO_IOS=1 - skips the ssc's iOS support. This is useful if you are not developing for iOS and don't want to install the iOS SDK. It's only useful on macOS.
  • CPU_CORES={number} - sets the number of CPU cores to use for the build. This is useful if you want to speed up the build process. The default value is the number of CPU cores on your machine.

Additional flags on Windows:

  • -debug - builds ssc in debug mode. This is useful if you are developing ssc and want to debug it.
  • -verbose - prints useful information about the build process. Please use this flag if you are reporting a bug.
  • -yesdeps - automatically installs the dependencies for Socket Runtime.

If you make any changes to the Socket Runtime JavaScript API source code, you should run npm run gen after running ./bin/install.sh or .\bin\install.ps1 to update the TypeScript type definitions for Socket Runtime and the API documentation.

./bin/publish-npm-modules.sh (macOS and Linux)

This command runs ./bin/install.sh, builds ssc npm packages and does npm link for the @socketsupply/socket package and platform-specific packages (if --link flag is provided, see description below). This allows you to use the latest version of Socket Runtime in your Socket Runtime applications without publishing the npm packages to npmjs.com registry. Just run npm link @socketsupply/socket in your Socket Runtime application directory and you are good to go and use your local version of Socket Runtime.

Useful flags:

  • --only-platforms - builds only the platform-specific npm packages.
  • --only-top-level - builds only the top-level npm package.
  • --link - runs npm link for the @socketsupply/socket package and platform-specific packages.

You don't have to run npm run gen after running ./bin/publish-npm-modules.sh because it runs npm run gen automatically.

./bin/clean.sh (macOS and Linux)

Sometimes you need to clean the build artifacts and start from scratch. This command removes the build artifacts for ssc and the Socket Runtime libraries.

Project directory structure

The project is structured as follows:

  1. api: The api folder contains the JavaScript API for Socket Runtime. It consists of the built-in modules that are available in the runtime and the socket package that is published to npm (i.e. socket:fs, socket:crypto, etc.). These modules have native bindings to the underlying C++/Objective-C/Kotlin code and libuv to expose the platform capabilities to the JavaScript code.

  2. bin: This directory contains useful scripts for building the project on different platforms, managing versions, generating documentation, publishing npm packages, etc.

  3. npm: This directory consists of the JavaScrip wrappers for the native code, build scripts and package directories. This directory consists of the JavaScrip wrappers for the native code, build scripts and package directories. You can also find the official Socket Runtime Node.js backend in the npm/packages/@socketsupply/socket-node directory.

  4. src: This directory contains the native code for the Socket Runtime:

    • android: contains the source code for the Socket Runtime library for Android
    • app: contains the source code related to the Socket Runtime application instance
    • cli: contains the source code for the Socket Runtime CLI
    • core: contains the source code for the Socket Runtime core, such as Bluetooth support, File System, UDP, Peer-to-Peer capabilities, JavaScript bindings, etc.
    • desktop: contains the source code for the Socket Runtime library for desktop platforms
    • extension: contains the source code for the Socket Runtime extensions ABI
    • ios: contains the source code for the Socket Runtime library for iOS
    • ipc: contains the source code for the Socket Runtime IPC library
    • process: contains the source code for the process management
    • window: contains the source code for the window management on desktop platforms

  5. test: This directory contains the actual Socket Runtime application that is used for testing the native code and the JavaScript API.

Building Socket Runtime applications

Once you have built ssc, you can use it to build Socket Runtime applications. ssc -h command prints the help message for ssc and lists all the available commands.

Check out the Guides for more information on how to build Socket Runtime applications.

Adding tests

We run Socket Runtime E2E tests from the actual Socket Runtime application located in the test directory. This allows us to test the Socket Runtime API from the perspective of the Socket Runtime application developer. The tests are written in JavaScript and use the built-in socket:test module to test the Socket Runtime API. socket:test is a port of the tapzero testing framework.

To run the tests, use the following command:

npm run test

You can also run specific tests against specific module by using the --test flag:

ssc run --test=application.js ./test

Be sure to build ssc before running the tests if you have made any changes to the Socket Runtime source code. You can also rebuild and run ssc with a single command:

ssc build -r --test=application.js ./test

Other repositories

  • Socket-Examples: This repository contains example projects powered by Socket which helps you build cross-platform apps for desktop and mobile.
  • Create-socket-app: This repository will help you build native apps for mobile and desktop with Svelte, Reactjs, Vuejs, and others, by providing a few basic boilerplates and some strong opinions so you can get coding on a production-quality app as quickly as possible.

Creating an issue

Issues for all Socket Runtime components are on GitHub. When reporting issues, please follow these guidelines:

  • If you think you have found a bug, Please open an issue and make sure that you select the correct template and follow the given instructions while creating an issue.
  • You can search through existing issues to see if there is a similar one reported. You can also search through closed issues as they may have been closed with a solution.
  • Please detail all the steps necessary to reproduce the issue you are running into, so we can easily diagnose and fix your issue.
  • If you have found a potential security issue, please use the GitHub Security Advisory Report a Vulnerability tab to report the issue. We will work with you the the entire lifecycle of the issue from the time you report it, to the time it has remediation, and is ready for an announcement.

If you can't find something in this guide or you have any questions, please feel free to join our Discord

Claiming Issues

If you find a bug or an issue that you would like to work on, you can ask to claim it, please leave a comment indicating your intention and we will assign it to you. If an issue is not being worked on, feel free to work on it yourself (but please comment first to let us know about your attention to work on it so the assignee knows).

Making Pull requests

Before submitting a pull request, please follow these steps:

  • Create an issue if one has not already been created.
  • Call out a reviewer to look at and merge your code, this helps our team to keep track of the pull requests and make sure there isn't duplicated effort.

Thanks for helping to improve Socket Runtime!