JavaScriptNexus/devicescript
Folders and files
| Name | Name | Last commit date | ||
|---|---|---|---|---|
Repository files navigation
<!doctype html> <html lang="en" dir="ltr" class="docs-wrapper docs-doc-page docs-version-current plugin-docs plugin-id-default docs-doc-id-contributing"> <head> <meta charset="UTF-8"> <meta name="generator" content="Docusaurus v2.4.1"> <title data-rh="true">Contributing | DeviceScript</title><meta data-rh="true" name="viewport" content="width=device-width,initial-scale=1"><meta data-rh="true" name="twitter:card" content="summary_large_image"><meta data-rh="true" property="og:url" content="https://microsoft.github.io/devicescript/contributing"><meta data-rh="true" name="docusaurus_locale" content="en"><meta data-rh="true" name="docsearch:language" content="en"><meta data-rh="true" name="docusaurus_version" content="current"><meta data-rh="true" name="docusaurus_tag" content="docs-default-current"><meta data-rh="true" name="docsearch:version" content="current"><meta data-rh="true" name="docsearch:docusaurus_tag" content="docs-default-current"><meta data-rh="true" property="og:title" content="Contributing | DeviceScript"><meta data-rh="true" name="description" content="Contributions are welcome! DeviceScript takes pull requests."><meta data-rh="true" property="og:description" content="Contributions are welcome! DeviceScript takes pull requests."><link data-rh="true" rel="icon" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fimg%2Ffavicon.svg"><link data-rh="true" rel="canonical" href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%3Ca+href%3D"https://microsoft.github.io/devicescript/contributing"><link" rel="nofollow">https://microsoft.github.io/devicescript/contributing"><link data-rh="true" rel="alternate" href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%3Ca+href%3D"https://microsoft.github.io/devicescript/contributing" rel="nofollow">https://microsoft.github.io/devicescript/contributing" hreflang="en"><link data-rh="true" rel="alternate" href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%3Ca+href%3D"https://microsoft.github.io/devicescript/contributing" rel="nofollow">https://microsoft.github.io/devicescript/contributing" hreflang="x-default"><link rel="stylesheet" href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%3Ca+href%3D"https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" rel="nofollow">https://cdn.jsdelivr.net/npm/[email protected]/dist/katex.min.css" integrity="sha384-odtC+0UGzzFL/6PNoE8rX/SPcQDXBJ+uRepguP4QkPCm2LBxH3FA3y+fKSiJ+AmM" crossorigin="anonymous"><link rel="stylesheet" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fassets%2Fcss%2Fstyles.83f5432f.css"> <link rel="preload" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fassets%2Fjs%2Fruntime%7Emain.5c9665ef.js" as="script"> <link rel="preload" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fassets%2Fjs%2Fmain.2ac68606.js" as="script"> </head> <body class="navigation-with-keyboard"> <script>!function(){function t(t){document.documentElement.setAttribute("data-theme",t)}var e=function(){var t=null;try{t=new URLSearchParams(window.location.search).get("docusaurus-theme")}catch(t){}return t}()||function(){var t=null;try{t=localStorage.getItem("theme")}catch(t){}return t}();t(null!==e?e:"light")}(),document.documentElement.setAttribute("data-announcement-bar-initially-dismissed",function(){try{return"true"===localStorage.getItem("docusaurus.announcement.dismiss")}catch(t){}return!1}())</script><div id="__docusaurus"> <div role="region" aria-label="Skip to main content"><a class="skipToContent_oPtH" href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23__docusaurus_skipToContent_fallback">Skip to main content</a></div><div class="announcementBar_zJRd" style="background-color:#fafbfc;color:#091E42" role="banner"><div class="announcementBarPlaceholder_NpUd"></div><div class="content_bSb_ announcementBarContent_t7IR">Experimental Project from Microsoft Research - Join the <a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%3Ca+href%3D"https://github.com/microsoft/devicescript/discussions">discussions</a">https://github.com/microsoft/devicescript/discussions">discussions</a> to provide feedback.</div><button type="button" aria-label="Close" class="clean-btn close closeButton_J5rP announcementBarClose_Jjdj"><svg viewBox="0 0 15 15" width="14" height="14"><g stroke="currentColor" stroke-width="3.1"><path d="M.75.75l13.5 13.5M14.25.75L.75 14.25"></path></g></svg></button></div><nav aria-label="Main" class="navbar navbar--fixed-top navbarHideable_hhpl"><div class="navbar__inner"><div class="navbar__items"><button aria-label="Toggle navigation bar" aria-expanded="false" class="navbar__toggle clean-btn" type="button"><svg width="30" height="30" viewBox="0 0 30 30" aria-hidden="true"><path stroke="currentColor" stroke-linecap="round" stroke-miterlimit="10" stroke-width="2" d="M4 7h22M4 15h22M4 23h22"></path></svg></button><a class="navbar__brand" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2F"><div class="navbar__logo"><img src="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fimg%2Flogo.svg" alt="DeviceScript language" class="themedImage_BQGR themedImage--light_HAxW"><img src="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fimg%2Flogo_dark.svg" alt="DeviceScript language" class="themedImage_BQGR themedImage--dark_bGx0"></div><b class="navbar__title text--truncate">DeviceScript</b></a><a aria-current="page" class="navbar__item navbar__link navbar__link--active" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fgetting-started">Download</a><a aria-current="page" class="navbar__item navbar__link navbar__link--active" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fintro">Docs</a><a aria-current="page" class="navbar__item navbar__link navbar__link--active" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fdevices">Devices</a><a aria-current="page" class="navbar__item navbar__link navbar__link--active" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fapi%2Fcli">API</a></div><div class="navbar__items navbar__items--right"><a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%3Ca+href%3D"https://github.com/microsoft/devicescript">https://github.com/microsoft/devicescript" target="_blank" rel="noopener noreferrer" class="navbar__item navbar__link header-github-link" aria-label="GitHub repository"></a><div class="toggle_ki11 colorModeToggle_Hewu"><button class="clean-btn toggleButton_MMFG toggleButtonDisabled_Uw7m" type="button" disabled="" title="Switch between dark and light mode (currently light mode)" aria-label="Switch between dark and light mode (currently light mode)" aria-live="polite"><svg viewBox="0 0 24 24" width="24" height="24" class="lightToggleIcon_lgto"><path fill="currentColor" d="M12,9c1.65,0,3,1.35,3,3s-1.35,3-3,3s-3-1.35-3-3S10.35,9,12,9 M12,7c-2.76,0-5,2.24-5,5s2.24,5,5,5s5-2.24,5-5 S14.76,7,12,7L12,7z M2,13l2,0c0.55,0,1-0.45,1-1s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S1.45,13,2,13z M20,13l2,0c0.55,0,1-0.45,1-1 s-0.45-1-1-1l-2,0c-0.55,0-1,0.45-1,1S19.45,13,20,13z M11,2v2c0,0.55,0.45,1,1,1s1-0.45,1-1V2c0-0.55-0.45-1-1-1S11,1.45,11,2z M11,20v2c0,0.55,0.45,1,1,1s1-0.45,1-1v-2c0-0.55-0.45-1-1-1C11.45,19,11,19.45,11,20z M5.99,4.58c-0.39-0.39-1.03-0.39-1.41,0 c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0s0.39-1.03,0-1.41L5.99,4.58z M18.36,16.95 c-0.39-0.39-1.03-0.39-1.41,0c-0.39,0.39-0.39,1.03,0,1.41l1.06,1.06c0.39,0.39,1.03,0.39,1.41,0c0.39-0.39,0.39-1.03,0-1.41 L18.36,16.95z M19.42,5.99c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06c-0.39,0.39-0.39,1.03,0,1.41 s1.03,0.39,1.41,0L19.42,5.99z M7.05,18.36c0.39-0.39,0.39-1.03,0-1.41c-0.39-0.39-1.03-0.39-1.41,0l-1.06,1.06 c-0.39,0.39-0.39,1.03,0,1.41s1.03,0.39,1.41,0L7.05,18.36z"></path></svg><svg viewBox="0 0 24 24" width="24" height="24" class="darkToggleIcon_U96C"><path fill="currentColor" d="M9.37,5.51C9.19,6.15,9.1,6.82,9.1,7.5c0,4.08,3.32,7.4,7.4,7.4c0.68,0,1.35-0.09,1.99-0.27C17.45,17.19,14.93,19,12,19 c-3.86,0-7-3.14-7-7C5,9.07,6.81,6.55,9.37,5.51z M12,3c-4.97,0-9,4.03-9,9s4.03,9,9,9s9-4.03,9-9c0-0.46-0.04-0.92-0.1-1.36 c-0.98,1.37-2.58,2.26-4.4,2.26c-2.98,0-5.4-2.42-5.4-5.4c0-1.81,0.89-3.42,2.26-4.4C12.92,3.04,12.46,3,12,3L12,3z"></path></svg></button></div><div class="searchBox_WqAV"></div></div></div><div role="presentation" class="navbar-sidebar__backdrop"></div></nav><div id="__docusaurus_skipToContent_fallback" class="main-wrapper mainWrapper_MB5r docsWrapper_ct1J"><button aria-label="Scroll back to top" class="clean-btn theme-back-to-top-button backToTopButton_iEvu" type="button"></button><div class="docPage_KLoz"><aside class="theme-doc-sidebar-container docSidebarContainer_y0RQ"><div class="sidebarViewport_EJ1r"><div class="sidebar_CUen sidebarWithHideableNavbar_w4KB"><a tabindex="-1" class="sidebarLogo_CYvI" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2F"><img src="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fimg%2Flogo.svg" alt="DeviceScript language" class="themedImage_BQGR themedImage--light_HAxW"><img src="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fimg%2Flogo_dark.svg" alt="DeviceScript language" class="themedImage_BQGR themedImage--dark_bGx0"><b>DeviceScript</b></a><nav aria-label="Docs sidebar" class="menu thin-scrollbar menu_jmj1 menuWithAnnouncementBar_YufC"><ul class="theme-doc-sidebar-menu menu__list"><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fintro">DeviceScript</a></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fgetting-started">Getting Started</a><button aria-label="Toggle the collapsible sidebar category 'Getting Started'" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fdeveloper">Developer</a><button aria-label="Toggle the collapsible sidebar category 'Developer'" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fsamples">Samples</a><button aria-label="Toggle the collapsible sidebar category 'Samples'" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Flanguage">Language Reference</a><button aria-label="Toggle the collapsible sidebar category 'Language Reference'" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist" aria-expanded="false" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fdevices">Devices</a><button aria-label="Toggle the collapsible sidebar category 'Devices'" type="button" class="clean-btn menu__caret"></button></div></li><li class="theme-doc-sidebar-item-category theme-doc-sidebar-item-category-level-1 menu__list-item menu__list-item--collapsed"><div class="menu__list-item-collapsible"><a class="menu__link menu__link--sublist menu__link--sublist-caret" aria-expanded="false" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fapi%2Fcli">API</a></div></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fchangelog">Release Notes</a></li><li class="theme-doc-sidebar-item-link theme-doc-sidebar-item-link-level-1 menu__list-item"><a class="menu__link menu__link--active" aria-current="page" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fcontributing">Contributing</a></li></ul></nav><button type="button" title="Collapse sidebar" aria-label="Collapse sidebar" class="button button--secondary button--outline collapseSidebarButton_oTwn"><svg width="20" height="20" aria-hidden="true" class="collapseSidebarButtonIcon_pMEX"><g fill="#7a7a7a"><path d="M9.992 10.023c0 .2-.062.399-.172.547l-4.996 7.492a.982.982 0 01-.828.454H1c-.55 0-1-.453-1-1 0-.2.059-.403.168-.551l4.629-6.942L.168 3.078A.939.939 0 010 2.528c0-.548.45-.997 1-.997h2.996c.352 0 .649.18.828.45L9.82 9.472c.11.148.172.347.172.55zm0 0"></path><path d="M19.98 10.023c0 .2-.058.399-.168.547l-4.996 7.492a.987.987 0 01-.828.454h-3c-.547 0-.996-.453-.996-1 0-.2.059-.403.168-.551l4.625-6.942-4.625-6.945a.939.939 0 01-.168-.55 1 1 0 01.996-.997h3c.348 0 .649.18.828.45l4.996 7.492c.11.148.168.347.168.55zm0 0"></path></g></svg></button></div></div></aside><main class="docMainContainer_sTIZ"><div class="container padding-top--md padding-bottom--lg"><div class="row"><div class="col docItemCol_Qr34"><div class="docItemContainer_tjFy"><article><nav class="theme-doc-breadcrumbs breadcrumbsContainer_T5ub" aria-label="Breadcrumbs"><ul class="breadcrumbs" itemscope="" itemtype="https://schema.org/BreadcrumbList"><li class="breadcrumbs__item"><a aria-label="Home page" class="breadcrumbs__link" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2F"><svg viewBox="0 0 24 24" class="breadcrumbHomeIcon_sfvy"><path d="M10 19v-5h4v5c0 .55.45 1 1 1h3c.55 0 1-.45 1-1v-7h1.7c.46 0 .68-.57.33-.87L12.67 3.6c-.38-.34-.96-.34-1.34 0l-8.36 7.53c-.34.3-.13.87.33.87H5v7c0 .55.45 1 1 1h3c.55 0 1-.45 1-1z" fill="currentColor"></path></svg></a></li><li itemscope="" itemprop="itemListElement" itemtype="https://schema.org/ListItem" class="breadcrumbs__item breadcrumbs__item--active"><span class="breadcrumbs__link" itemprop="name">Contributing</span><meta itemprop="position" content="1"></li></ul></nav><div class="tocCollapsible_wXna theme-doc-toc-mobile tocMobile_Ojys"><button type="button" class="clean-btn tocCollapsibleButton_iI2p">On this page</button></div><div class="theme-doc-markdown markdown"><h1>Contributing</h1><p><strong>Contributions are welcome!</strong> DeviceScript takes pull requests.</p><h2 class="anchor anchorWithHideOnScrollNavbar_pMLv" id="contributions">Contributions<a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23contributions" class="hash-link" aria-label="Direct link to Contributions" title="Direct link to Contributions"></a></h2><p>We have a few guides to help with specific contributions.</p><ul><li><a href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fdeveloper%2Fdrivers%2Fadd-driver">add a new driver</a></li><li><a href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fdevices%2Fadd-board">add a new board</a></li><li><a href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fdevices%2Fadd-shield">add a new shield</a></li><li><a href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fdevices%2Fadd-soc">add a new SOC</a></li></ul><h3 class="anchor anchorWithHideOnScrollNavbar_pMLv" id="samples">Samples<a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23samples" class="hash-link" aria-label="Direct link to Samples" title="Direct link to Samples"></a></h3><p>Documentation samples are located under <code>website/docs/samples</code>. Each <code>.mdx</code> file contains a single self-contained sample.</p><p>It is typically easiest to develop a sample in a dedicate <code>.ts</code> file to leverage the editor's features, and then copy it to the <code>.mdx</code> file.</p><p>To run the docs locally, run <code>yarn docs</code>. This will launch the docusaurus development server and refresh the documentation page on each edit.</p><p>If your sample requires multiple files, such as images,</p><ul><li>create a folder with the same name as the <code>.mdx</code> file</li><li>move your <code>.mdx</code> file and rename it to <code>index.mdx</code></li><li>add a <code>_category_.json</code> file with the front matter</li></ul><div class="language-json codeBlockContainer_mQmQ theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_D5yF"><pre tabindex="0" class="prism-code language-json codeBlock_RMoD thin-scrollbar"><code class="codeBlockLines_AclH"><span class="token-line" style="color:#393A34"><span class="token punctuation" style="color:#393A34">{</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#005CC5">"label"</span><span class="token operator" style="color:#D73A49">:</span><span class="token plain"> </span><span class="token string" style="color:#C6105F">"Samples"</span><span class="token punctuation" style="color:#393A34">,</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"> </span><span class="token property" style="color:#005CC5">"position"</span><span class="token operator" style="color:#D73A49">:</span><span class="token plain"> </span><span class="token number" style="color:#005CC5">3</span><span class="token plain"></span><br></span><span class="token-line" style="color:#393A34"><span class="token plain"></span><span class="token punctuation" style="color:#393A34">}</span><br></span></code></pre><div class="buttonGroup_aaMX"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_z5j7" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_FoOz"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_L0B6"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><h2 class="anchor anchorWithHideOnScrollNavbar_pMLv" id="local-development">Local development<a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23local-development" class="hash-link" aria-label="Direct link to Local development" title="Direct link to Local development"></a></h2><p>The development requirement will vary (widely) depending on which part of DeviceScript you want to work on.</p><p>Using Visual Studio Code is strongly recommended.</p><h3 class="anchor anchorWithHideOnScrollNavbar_pMLv" id="repository-structure">Repository structure<a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23repository-structure" class="hash-link" aria-label="Direct link to Repository structure" title="Direct link to Repository structure"></a></h3><p>This repository contains:</p><ul><li><a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%3Ca+href%3D"https://github.com/microsoft/jacdac-c">https://github.com/microsoft/jacdac-c" target="_blank" rel="noopener noreferrer">jacdac-c submodule</a>, including sources for Jacdac client libraries and DeviceScript VM</li><li><code>compiler/</code> - sources for DeviceScript compiler</li><li><code>runtime/devicescript-vm/</code> - glue files to build DeviceScript VM as WASM module using <a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%3Ca+href%3D"https://emscripten.org/" rel="nofollow">https://emscripten.org/" target="_blank" rel="noopener noreferrer">emscripten</a>; <code>vm/dist/</code> contain pre-built files</li><li><code>packages</code> - builtin packages and sample project (<code>packages/sampleprj</code>)</li><li><code>runtime/posix/</code> - implementation of Jacdac SDK HAL for grown-up POSIX-like operating systems (as opposed to embedded platforms)</li><li><code>vscode</code> - Visual Studio Code extension</li><li><code>website</code> - docusaurus documentation side</li></ul><h3 class="anchor anchorWithHideOnScrollNavbar_pMLv" id="compiler-runtime-and-command-line">Compiler, runtime and command line<a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23compiler-runtime-and-command-line" class="hash-link" aria-label="Direct link to Compiler, runtime and command line" title="Direct link to Compiler, runtime and command line"></a></h3><p>You can use the devcontainer to build. The instructions are tested for a Unix terminal.</p><p>If you want to build locally you need to install node.js. After cloning, the repo run</p><div class="language-bash codeBlockContainer_mQmQ theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_D5yF"><pre tabindex="0" class="prism-code language-bash codeBlock_RMoD thin-scrollbar"><code class="codeBlockLines_AclH"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#8250DF">yarn</span><span class="token plain"> setup</span><br></span></code></pre><div class="buttonGroup_aaMX"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_z5j7" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_FoOz"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_L0B6"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><p>To run a watch build and the docs, run</p><div class="codeBlockContainer_mQmQ theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_D5yF"><pre tabindex="0" class="prism-code language-text codeBlock_RMoD thin-scrollbar"><code class="codeBlockLines_AclH"><span class="token-line" style="color:#393A34"><span class="token plain">nvm use 18</span><br></span><span class="token-line" style="color:#393A34"><span class="token plain">yarn dev</span><br></span></code></pre><div class="buttonGroup_aaMX"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_z5j7" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_FoOz"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_L0B6"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><ul><li>start <code>jacdac devtools</code> (the npm version) and let it run</li><li>open this folder in VSCode; use "Reopen in Container" if needed</li><li>start Terminal in VSCode</li><li>run <code>yarn install</code></li><li>run <code>yarn build</code></li><li>run <code>yarn devs run devs/samples/something.ts</code> - this will execute given DeviceScript program using the WASM binary</li></ul><p>If you want to develop the runtime (as opposed to compiler or website), you will also need GNU Make, C compiler, and <a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%3Ca+href%3D"https://emscripten.org/docs/getting_started/downloads.html" rel="nofollow">https://emscripten.org/docs/getting_started/downloads.html" target="_blank" rel="noopener noreferrer">emscripten</a>. Once you have it all:</p><ul><li>run <code>make native</code> to compile using native C compiler</li><li>run <code>yarn devs crun devs/samples/something.ts</code> - this will execute given DeviceScript program using the POSIX/native binary</li><li>run <code>./runtime/built/jdcli 8082</code> - this will run the POSIX/native DeviceScript server, which can be accessed from the devtools dashboard</li><li>run <code>make em</code> to compile using emscripten</li></ul><p>To lint sources,</p><ul><li>run <code>yarn lint</code></li></ul><h3 class="anchor anchorWithHideOnScrollNavbar_pMLv" id="visual-studio-extension">Visual Studio Extension<a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23visual-studio-extension" class="hash-link" aria-label="Direct link to Visual Studio Extension" title="Direct link to Visual Studio Extension"></a></h3><p>Open the Debug view in VSCode and run the <code>VSCode Extension</code> configuration. This will launch a new VSCode instance with the extension loaded. A build is automatically triggered before launch VSCode.</p><h3 class="anchor anchorWithHideOnScrollNavbar_pMLv" id="building-packages">Building packages<a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23building-packages" class="hash-link" aria-label="Direct link to Building packages" title="Direct link to Building packages"></a></h3><p>Similar to working on the Visual Studio Code extension, lunch the <code>VSCode Extension</code> debugger configuration. This will launch a new VSCode instance with the extension loaded. It should also open the <code>packages</code> folder which will allow you to work on the built-in packages.</p><h3 class="anchor anchorWithHideOnScrollNavbar_pMLv" id="documentation">Documentation<a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23documentation" class="hash-link" aria-label="Direct link to Documentation" title="Direct link to Documentation"></a></h3><p>Run <code>yarn docs</code> and edit any markdown file in the <code>website/docs</code> folder. The changes should be automatically picked up and rendered by docusaurus.</p><h3 class="anchor anchorWithHideOnScrollNavbar_pMLv" id="add-core-javascript-apis">Add Core JavaScript APIs<a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23add-core-javascript-apis" class="hash-link" aria-label="Direct link to Add Core JavaScript APIs" title="Direct link to Add Core JavaScript APIs"></a></h3><p>The DeviceScript <a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%3Ca+href%3D"https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects" rel="nofollow">https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects" target="_blank" rel="noopener noreferrer">core js library</a> is not complete; but it is possible to fill the gaps as needed. The requests are tracked by the <a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%3Ca+href%3D"https://github.com/microsoft/devicescript/issues?q=is%3Aissue+is%3Aopen+label%3A%22core+js%22">https://github.com/microsoft/devicescript/issues?q=is%3Aissue+is%3Aopen+label%3A%22core+js%22" target="_blank" rel="noopener noreferrer">core js issue label</a>.</p><p>You will need a local development setup for these tasks.</p><p>If you want to add a new function:</p><ul><li>find the corresponding function definition in one of the <code>lib/es....d.ts</code> file.</li><li>copy the definition in the corresponding interface in <code>packages/core/src/corelib.d.ts</code></li><li>implement the function in the implementation file of the type (see <code>packages/core/src/array.ts</code> for example). If you are adding a new file, make sure to import it in <code>packages/core/src/index.ts</code>.</li><li>add test cases in the corresponding test file under <code>devs/run-tests</code></li><li>build and test</li><li>create a pull request and go!</li></ul><p>If you want to add a new Type, we currently have a limitation with the <code>core</code> package and you will need to add it to the <code>runtime</code> package:s</p><ul><li>implement the class in the implementation file of the type (see <code>packages/runtime/src/map.ts</code> for example). If you are adding a new file, make sure to import it in <code>packages/runtime/src/map.ts</code>.</li><li>add test cases in the corresponding test file under <code>packages/runtime/src/main.ts</code></li><li>build and test</li><li>create a pull request and go!</li></ul><h3 class="anchor anchorWithHideOnScrollNavbar_pMLv" id="documentingpatching-console-output">Documenting/patching console output<a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23documentingpatching-console-output" class="hash-link" aria-label="Direct link to Documenting/patching console output" title="Direct link to Documenting/patching console output"></a></h3><p>To add new substitions from console output message to pretty text + URL, do the following.</p><p>The <code>website/docs/developer/errors.mdx</code> gets parsed by builderrors.mjs. The hash of the H2 titles is the console log look up key (replacing - with spaces) and the H2 text will replace that key + URL.</p><div class="codeBlockContainer_mQmQ theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_D5yF"><pre tabindex="0" class="prism-code language-text codeBlock_RMoD thin-scrollbar"><code class="codeBlockLines_AclH"><span class="token-line" style="color:#393A34"><span class="token plain">loopback rx ovf --> Loopback buffer overflow (....#loopback-rx-ovf)</span><br></span></code></pre><div class="buttonGroup_aaMX"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_z5j7" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_FoOz"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_L0B6"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><h3 class="anchor anchorWithHideOnScrollNavbar_pMLv" id="adding-builtin-packages">Adding Builtin Packages<a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23adding-builtin-packages" class="hash-link" aria-label="Direct link to Adding Builtin Packages" title="Direct link to Adding Builtin Packages"></a></h3><p>Adding a new package is more advanced scenario and most likely we should have a discussion prior to start this work. You are welcome to publish packages under your account in npm.</p><blockquote><p>A good question to start with: Do we need a new builtin package or should it be a new npm package?</p></blockquote><p>Generally, search for <code>@devicescript/gpio</code> within the workspace. The main places that need updating is:</p><ul><li>this file, <code>website/docs/developer/packages.mdx</code></li><li>list in <code>plugin/src/plugin.ts</code></li><li>list in <code>devs/run-test/allcompile.ts</code></li></ul><p>After adding a new packages, run <code>yarn</code> at the top-level to update workspace links, followed by the usual <code>yarn build</code>.</p><h2 class="anchor anchorWithHideOnScrollNavbar_pMLv" id="release-process">Release process<a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23release-process" class="hash-link" aria-label="Direct link to Release process" title="Direct link to Release process"></a></h2><p>Run <code>yarn bump</code> (or <code>make bump</code>). Alternatively, edit <code>img_version_patch</code> in <code>bytecode/bytecode.md</code> and push.</p><p>The cloud build will rebuild and check-in the VM, update version numbers in all <code>package.json</code> files, and publish them.</p><p>If you bump minor, you need to also bump the firmware repos:</p><ul><li>go to each firmware repo (<a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%3Ca+href%3D"https://github.com/microsoft/devicescript-esp32">https://github.com/microsoft/devicescript-esp32" target="_blank" rel="noopener noreferrer">https://github.com/microsoft/devicescript-esp32</a>, <a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%3Ca+href%3D"https://github.com/microsoft/devicescript-pico">https://github.com/microsoft/devicescript-pico" target="_blank" rel="noopener noreferrer">https://github.com/microsoft/devicescript-pico</a>, <a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%3Ca+href%3D"https://github.com/microsoft/devicescript-stm32">https://github.com/microsoft/devicescript-stm32" target="_blank" rel="noopener noreferrer">https://github.com/microsoft/devicescript-stm32</a>)</li><li>update the <code>devicescript</code> submodule</li><li>run</li></ul><div class="language-bash codeBlockContainer_mQmQ theme-code-block" style="--prism-color:#393A34;--prism-background-color:#f6f8fa"><div class="codeBlockContent_D5yF"><pre tabindex="0" class="prism-code language-bash codeBlock_RMoD thin-scrollbar"><code class="codeBlockLines_AclH"><span class="token-line" style="color:#393A34"><span class="token function" style="color:#8250DF">make</span><span class="token plain"> bump</span><br></span></code></pre><div class="buttonGroup_aaMX"><button type="button" aria-label="Copy code to clipboard" title="Copy" class="clean-btn"><span class="copyButtonIcons_z5j7" aria-hidden="true"><svg viewBox="0 0 24 24" class="copyButtonIcon_FoOz"><path fill="currentColor" d="M19,21H8V7H19M19,5H8A2,2 0 0,0 6,7V21A2,2 0 0,0 8,23H19A2,2 0 0,0 21,21V7A2,2 0 0,0 19,5M16,1H4A2,2 0 0,0 2,3V17H4V3H16V1Z"></path></svg><svg viewBox="0 0 24 24" class="copyButtonSuccessIcon_L0B6"><path fill="currentColor" d="M21,7L9,19L3.5,13.5L4.91,12.09L9,16.17L19.59,5.59L21,7Z"></path></svg></span></button></div></div></div><h2 class="anchor anchorWithHideOnScrollNavbar_pMLv" id="legal">Legal<a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23legal" class="hash-link" aria-label="Direct link to Legal" title="Direct link to Legal"></a></h2><p>This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit <a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%3Ca+href%3D"https://cla.opensource.microsoft.com" rel="nofollow">https://cla.opensource.microsoft.com" target="_blank" rel="noopener noreferrer">https://cla.opensource.microsoft.com</a>.</p><p>When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.</p><p>This project has adopted the <a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%3Ca+href%3D"https://opensource.microsoft.com/codeofconduct/" rel="nofollow">https://opensource.microsoft.com/codeofconduct/" target="_blank" rel="noopener noreferrer">Microsoft Open Source Code of Conduct</a>. For more information see the <a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%3Ca+href%3D"https://opensource.microsoft.com/codeofconduct/faq/" rel="nofollow">https://opensource.microsoft.com/codeofconduct/faq/" target="_blank" rel="noopener noreferrer">Code of Conduct FAQ</a> or contact <a href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fmailto%3Aopencode%40microsoft.com" target="_blank" rel="noopener noreferrer">[email protected]</a> with any additional questions or comments.</p></div></article><nav class="pagination-nav docusaurus-mt-lg" aria-label="Docs pages"><a class="pagination-nav__link pagination-nav__link--prev" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fchangelog"><div class="pagination-nav__sublabel">Previous</div><div class="pagination-nav__label">Release Notes</div></a></nav></div></div><div class="col col--3"><div class="tableOfContents_XG6w thin-scrollbar theme-doc-toc-desktop"><ul class="table-of-contents table-of-contents__left-border"><li><a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23contributions" class="table-of-contents__link toc-highlight">Contributions</a><ul><li><a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23samples" class="table-of-contents__link toc-highlight">Samples</a></li></ul></li><li><a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23local-development" class="table-of-contents__link toc-highlight">Local development</a><ul><li><a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23repository-structure" class="table-of-contents__link toc-highlight">Repository structure</a></li><li><a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23compiler-runtime-and-command-line" class="table-of-contents__link toc-highlight">Compiler, runtime and command line</a></li><li><a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23visual-studio-extension" class="table-of-contents__link toc-highlight">Visual Studio Extension</a></li><li><a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23building-packages" class="table-of-contents__link toc-highlight">Building packages</a></li><li><a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23documentation" class="table-of-contents__link toc-highlight">Documentation</a></li><li><a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23add-core-javascript-apis" class="table-of-contents__link toc-highlight">Add Core JavaScript APIs</a></li><li><a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23documentingpatching-console-output" class="table-of-contents__link toc-highlight">Documenting/patching console output</a></li><li><a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23adding-builtin-packages" class="table-of-contents__link toc-highlight">Adding Builtin Packages</a></li></ul></li><li><a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23release-process" class="table-of-contents__link toc-highlight">Release process</a></li><li><a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23legal" class="table-of-contents__link toc-highlight">Legal</a></li></ul></div></div></div></div></main></div></div><footer class="footer footer--dark"><div class="container container-fluid"><div class="row footer__links"><div class="col footer__col"><div class="footer__title">Docs</div><ul class="footer__items clean-list"><li class="footer__item"><a class="footer__link-item" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fintro">Introduction</a></li><li class="footer__item"><a class="footer__link-item" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fdeveloper">Developer</a></li><li class="footer__item"><a class="footer__link-item" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Flanguage">Language Reference</a></li><li class="footer__item"><a class="footer__link-item" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fapi%2Fcli">API</a></li></ul></div><div class="col footer__col"><div class="footer__title">Info</div><ul class="footer__items clean-list"><li class="footer__item"><a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%3Ca+href%3D"https://github.com/microsoft/devicescript/">https://github.com/microsoft/devicescript/" target="_blank" rel="noopener noreferrer" class="footer__link-item">GitHub<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPrP"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%3Ca+href%3D"https://github.com/microsoft/devicescript/discussions">https://github.com/microsoft/devicescript/discussions" target="_blank" rel="noopener noreferrer" class="footer__link-item">Discussions<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPrP"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%3Ca+href%3D"https://go.microsoft.com/fwlink/?linkid=2259814" rel="nofollow">https://go.microsoft.com/fwlink/?linkid=2259814" target="_blank" rel="noopener noreferrer" class="footer__link-item">Consumer Health Privacy<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPrP"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li></ul></div><div class="col footer__col"><div class="footer__title">Legal</div><ul class="footer__items clean-list"><li class="footer__item"><a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%3Ca+href%3D"https://go.microsoft.com/fwlink/?LinkId=521839" rel="nofollow">https://go.microsoft.com/fwlink/?LinkId=521839" target="_blank" rel="noopener noreferrer" class="footer__link-item">Privacy & Cookies<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPrP"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%3Ca+href%3D"https://www.microsoft.com/en-us/legal/intellectualproperty/copyright" rel="nofollow">https://www.microsoft.com/en-us/legal/intellectualproperty/copyright" target="_blank" rel="noopener noreferrer" class="footer__link-item">Terms of Use<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPrP"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li><li class="footer__item"><a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%3Ca+href%3D"https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general" rel="nofollow">https://www.microsoft.com/en-us/legal/intellectualproperty/trademarks/usage/general" target="_blank" rel="noopener noreferrer" class="footer__link-item">Trademarks<svg width="13.5" height="13.5" aria-hidden="true" viewBox="0 0 24 24" class="iconExternalLink_nPrP"><path fill="currentColor" d="M21 13v10h-21v-19h12v2h-10v15h17v-8h2zm3-12h-10.988l4.035 4-6.977 7.07 2.828 2.828 6.977-7.07 4.125 4.172v-11z"></path></svg></a></li></ul></div></div><div class="footer__bottom text--center"><div class="footer__copyright">Copyright © 2024 Microsoft Corporation.</div></div></div></footer></div> <script src="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fassets%2Fjs%2Fruntime%7Emain.5c9665ef.js"></script> <script src="proxy.php?url=https%3A%2F%2Fgithub.com%2Fdevicescript%2Fassets%2Fjs%2Fmain.2ac68606.js"></script> </body> </html>
Languages
- TypeScript 59.5%
- C 23.0%
- MDX 14.3%
- JavaScript 2.0%
- Python 0.5%
- CSS 0.2%
- Other 0.5%