# Code App Documentation

Code App is a MIT-licensed desktop-class code editor for iPadOS with built-in Node.js, Python, C, C++, PHP and Java runtime.

We built it because there is nothing else on the App Store provides all these features in one app:

* A robust, high-performance text editor (Monaco Editor from Visual Studio Code)
* First class local file system support
* Extensive local language support
* SSH / FTP remote connection support (Files and terminal)
* Embedded emulated terminal
* Git Version Control
* Package manager support (pip and npm)
* Markdown, themes, server-side snippet execution and more

{% hint style="info" %}
While we want to make the editing experience as close as a desktop offers, Code App is still bounded by iOS's limitations. For example, you cannot download arbitary commands or modules with native components. Spawning subprocesses is also not possible.
{% endhint %}

![Compiling a C++ file with Clang](/files/TaiHvqY84aL1fHMrJhUs)

## Getting Started

### Installation

You can either install the app from App Store or TestFlight.

{% embed url="<https://apps.apple.com/us/app/code-app/id1512938504>" %}
Link to App Store ($5.99)
{% endembed %}

{% embed url="<https://testflight.apple.com/join/EgZ8sE2P>" %}
Link to TestFlight (Free)
{% endembed %}

Or if you'd like to get your hands dirty (Requires a Mac with Xcode installed) :&#x20;

{% embed url="<https://github.com/thebaselab/codeapp>" %}
Link to our repo
{% endembed %}

### Jump right in

Follow these guides to get started on the basics:

{% content-ref url="/pages/Ij7JZZwaKlNYFzlTYCLT" %}
[Getting familiar](/guides/getting-familiar)
{% endcontent-ref %}

{% content-ref url="/pages/pxYrsgCQZJfZ4bYqVbs9" %}
[Your first program in Python](/guides/your-first-program-in-python)
{% endcontent-ref %}

{% content-ref url="/pages/pVKdO12Ewvkg6ciAXmPB" %}
[Creating a Node.js project](/guides/creating-a-node.js-project)
{% endcontent-ref %}

{% content-ref url="/pages/3CJzJ5DgWsnEHK1O3ZnC" %}
[Version Control](/guides/version-control)
{% endcontent-ref %}

{% content-ref url="/pages/v3E3KgS8mCy1A7xX9W4a" %}
[Connecting to a remote server (SSH/FTP)](/guides/connecting-to-a-remote-server-ssh-ftp)
{% endcontent-ref %}

### Other Resources

{% content-ref url="/pages/8YBlPspnAdRKtff62der" %}
[Building Code from source](/extras/building-code-from-source)
{% endcontent-ref %}

{% content-ref url="/pages/jmgtPMko1MeU6bQ1TPTq" %}
[Frequently Asked Questions](/extras/frequently-asked-questions)
{% endcontent-ref %}

{% content-ref url="/pages/ZeA0iprHgpsHZ3uPtyZM" %}
[Supported Languages](/extras/supported-languages)
{% endcontent-ref %}


# Getting familiar

An overview of Code App's interface and main features.

<figure><img src="/files/us4Juufa5PYbsE8xkv0d" alt=""><figcaption></figcaption></figure>

## Files and Documents

### Workspace

A workspace is the root folder of the editor. It defines the files and folders displayed in the file explorer, as well as the working directory of the built-in terminal.

The default workspace folder is set as Code's Documents folder, which can be access in the Files App  `On My iPad > Code`. To set it as an other directory, tap the open folder icon in explorer (folder with a gear) and select any folder from Files App, including iCloud directories. Alternatively, tap and hold the folder's name and select `Assign as workspace folder`.

{% hint style="info" %}
To access files from OneDrive or other cloud providers, you might need to use the open file option instead, due to the platform's limitation.
{% endhint %}

To exit a workspace folder, select Close workspace in the quick menu at the top right corner.

### Creating files and folders

To create files and folder at the root folder, tap on the corresponding icon in the file explorer. To create files or folders in subfolders, tap and hold their names and select the relevant options.

### Importing a external project

Use the source control feature to clone your projects or explore community-maintained template projects for Code App. To learn more:

{% content-ref url="/pages/3CJzJ5DgWsnEHK1O3ZnC" %}
[Version Control](/guides/version-control)
{% endcontent-ref %}

### Access files from a SSH / FTP remote

You can access files hosted on a remote machine using Code App. To learn more:

{% content-ref url="/pages/v3E3KgS8mCy1A7xX9W4a" %}
[Connecting to a remote server (SSH/FTP)](/guides/connecting-to-a-remote-server-ssh-ftp)
{% endcontent-ref %}

## Languages

### Executing a program

Code App shows a play button at the top right corner for supported languages. Tap to execute the program. For languages that requires remote execution, the play button is shown along a server icon.

<figure><img src="/files/UoTDgM14FweHp9yamxYD" alt=""><figcaption></figcaption></figure>

To use custom compile flags, directly enter the command in the terminal. Supported commands include `java`, `javac`, `clang`, `clang++`, `python`, `node`, `php` etc.

{% content-ref url="/pages/pxYrsgCQZJfZ4bYqVbs9" %}
[Your first program in Python](/guides/your-first-program-in-python)
{% endcontent-ref %}

{% content-ref url="/pages/pVKdO12Ewvkg6ciAXmPB" %}
[Creating a Node.js project](/guides/creating-a-node.js-project)
{% endcontent-ref %}

## Editor

### Saving a file

Code App automatically saves your file when you hide the keyboard or exit the app.

### Switching between Monaco Editor and Runestone editor

<figure><img src="/files/S5BoszXO9P1hxMnSklw6" alt=""><figcaption><p>Native text selection using Runestone editor</p></figcaption></figure>

You may notice the default editor (Monaco) does not support native text selection using touch controls. Consider switching to Runestone editor mode when you are using the app without a physical keyboard. To do this, select switch to editor in the quick menu at the top right corner.&#x20;


# Your first program in Python

Learn to write Python script and install third party packages using pip.

Code App comes with many built-in languages including C++, Python and others. To see the full list, click the link below:

{% content-ref url="/pages/ZeA0iprHgpsHZ3uPtyZM" %}
[Supported Languages](/extras/supported-languages)
{% endcontent-ref %}

### A Hello World program in Python

Let's start by creating a Python source file. Expand the file explorer side bar and select the new file icon (document with a plus icon). You can either use the built in template or enter a custom file name to create an empty file.

For now, let's use the built in template.

![Creating a new file](/files/PGGEeW00fEE81ji92Lyn)

You should now see the hello world program written in Python. Tap the play button to run it.&#x20;

![Runing a Hello World program in Python](/files/bJQw7EAAatTLxu21ZM3L)

Congratulations! You now ran your first program on Code App.

### Python - Installing a third party module

Third party modules allow you to do awesome things, including making network requests to a web server, drawing charts to analysis data, or downloading a YouTube video.&#x20;

Code App comes with the `pip` command in the terminal. To install a modules, just type `pip install <module name>` in the terminal.

{% hint style="info" %}
Note that not all modules work on Code App, see the [FAQ](/extras/frequently-asked-questions#my-favourite-npm-python-module-doesnt-work) for more.
{% endhint %}

In this example, we will try out the `requests` module. It allows Python to make network requests to web servers. Let's try to get the list of people currently in the space.

Tap on the chevron button to bring up the terminal and type `pip install requests` in the terminal.

![Installing requests](/files/BFoNHH3CEqBG1Y7SKGnd)

Copy the following code to your source file and click run:

```python
import requests

res = requests.get('http://api.open-notify.org/astros.json')
print(res.text)
```

![Getting the list of all astronauts on ISS](/files/ld1phOAHw5bdQZJyfi56)

Cool! You now have the list of all astronauts currently on their mission in the space.&#x20;


# Creating a Node.js project

In this guide, we will build a simple web server using Node.js and Express.

### Creating a new folder

Let's start by creating a folder to organise our project. In the file explorer section, tap on the create folder button to create a new folder. Hold the folder cell and rename the folder. You can now assign as it as the workpalce folder.

![Assigning a folder as workplace folder](/files/AHYxNAvTUxnbogY4rEQl)

### Installing npm modules

In this project, we will be using a third party npm module called `Express`. Install it by running `npm i express` in the terminal. You will now see a folder called `node_modules` that contains the module we just installed. Another file created is `package.json`, it stores the list of dependencies as well as other information of your project. You can learn more about npm here: <https://docs.npmjs.com/cli/v7/configuring-npm/package-json>

### Implementing the server

Creating a web server using Express is super simple. Create a new file `index.js` and copy the following code.

```javascript
const express = require('express');

const app = express();
const port = 3000;

app.get('/', (req, res) => {
    res.send('Hello from Express')
})

app.listen(port, () => console.log(`app listening on port ${port}`))
```

Tap the run button on type `node index.js` in the terminal to run the server. Launch Safari side-by-side and visit `localhost:3000`. You now have yourself an Express server :).

![An express server running on Code App](/files/OJzMYWJkKgsltZxgkyhl)

To stop the server, press the stop (square) button located at the top right corner of the terminal tab.

### React projects

A list of community-maintainted template projects including a React starter project can be found in the source control tab,.&#x20;


# Version Control

Use the built-in support for Git to manage your code.

{% hint style="warning" %}
Command line git is unavailble because of a licensing issue. Use lg2 or the GUI instead.
{% endhint %}

### Set up your identities

Git uses name and email address identify the author of each commit. Before making a commit, you'll need to set up your identity.

To proceed, go `Settings > Version Control > Identity`.&#x20;

### Set up your credentials

If you are cloning a private repository or pushing changes to a remote, you'll need to set up credentials. To start, enter your credentials at `Settings > Version Control > Authentication`.

#### Password-based Authentication

The easiest way to authenticate in Git is to use password-based authentication. To start, obtain a personal access token from your Git hosting provider. To learn more:

{% embed url="<https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token>" %}
Creating a personal access token on GitHub
{% endembed %}

{% embed url="<https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html>" %}
Creating a personal access tokeno on GitLab
{% endembed %}

#### Key-based Authentication

SSH keys can also be used to authenicate in Git. To start, generate a SSH key pair and configure them in your Git hosting provider. To learn more:

{% embed url="<https://docs.github.com/en/authentication/connecting-to-github-with-ssh>" %}
Connecting to GitHub with SSH keys
{% endembed %}

{% embed url="<https://docs.gitlab.com/ee/user/ssh.html>" %}
Connecting to GitLab with SSH keys
{% endembed %}

#### Setting up multiple credentials

Code App supports multiple credentials. You can configure a unique credential for each hosting provider by specifying their hostnames during the setup process.

<figure><img src="/files/nb7mro7PDKdS4dWRTAn0" alt=""><figcaption><p>Hostname-based credentials</p></figcaption></figure>

### Cloning a repository

To clone a repository, tap the source control icon in the sidebar and enter its url in the clone repository section. Assign it as the workspace folder by tapping the open folder button.

{% hint style="info" %}
Workspace folder is the folder the editor currently loaded. To work with a git repository, it must be located at the root of the workspace folder. You can load a folder by holding a folder cell in explorer or by using the `code` command in the terminal.
{% endhint %}

<figure><img src="/files/hAm2GJB1xf9ew7Fhq1u0" alt=""><figcaption><p>Cloning a repository</p></figcaption></figure>

#### Community Templates

A list of community-maintained projects for Code App can be found and cloned under the community templates section.

### Committing files

Newly added / modified files must be added to the staging area before you can make a commit. To do this, press the plus icon next to the file name.

![Adding a file to staging area](/files/MSsjSl2wbFRqMG6BF9KU)

You can now enter a commit message in the textfield and press the commit button to commit. You can also use the `command`+`enter` shortcut.

### Pushing to remote

You can push your changes to your hosting provider like GitHub.

![Pushing changes to remote](/files/HCdbvUyi0zWDup5vzobW)

### Branches and tags

To checkout a branch or a tag, tap the branch icon located in the bottom left corner and select one.

![Checkout to a branch](/files/nVGsmoHWnfbhNQJKyfPQ)

### Pull and Fetch

You can also pull or fetch changes from remote. Pull immediately applies the upstream changes to your files. It does so by fast-forwarding the upstream commits if possible or attempting to merge otherwise. On the other hand, fetch does not write changes to your files.

<figure><img src="/files/clrzVNeYdOJ9AejsXHzP" alt=""><figcaption><p>Pull from a remote</p></figcaption></figure>

To learn more about git pull and fetch:

{% embed url="<https://git-scm.com/docs/git-pull>" %}

{% embed url="<https://git-scm.com/docs/git-fetch>" %}


# Connecting to a remote server (SSH/FTP)

Connect to a self-hosted server and get access to its files, terminal and network resources.

### Set up your remote server

Before using this feature, you'll need to set up a SSH (SFTP) or FTP server on your computer or server. On a Mac, you can do this by enabling Remote Login and full disk access in the `Sharing` section of System Preferences.

![Enabling SSH server on a Mac](/files/pfABW8Y47JhyPjPwILET)

### Set up a new remote in Code App

Open the remote section in the side bar and enter the server's information. Enable `Remember credentials` to save the credentials. Code App will ask for Face ID or Touch ID authentication when you connect to the server again in the future.

![Setting up a new remote](/files/CnqH9w0bJmV5i3Cdg3jf)

### Key Authentication

Besides password, SSH keys can also be used to authenticate your server. To do so, enable the `Use key authentication` option and enter your private key.&#x20;

#### Generating key-pairs in Code App

If you don't already have a key-pair, you can generate one with the `ssh-keygen` command in the terminal. You might need to specify the type of keys to generate depending on your server's configuration. For example on macOS Ventura, the default generated RSA key pair is not supported. You can generate a ed25519 key-pair instead by running `ssh-keygen -t ed25519`.

Then, copy the public key to your server's `authorized_keys` file. On macOS, it is located at `~/.ssh/authorized_keys.`

### Finishing up

Congratulations! You can now access the remote server's files and terminal.

{% hint style="info" %}
**Good to know:** Only SSH server allows terminal access
{% endhint %}

![](/files/7vszfZVrKEgZsyx3BnuX)

### Port forwarding (SSH Tunneling)

After successfully connecting to your remote server, you can set up port forwarding to access the server's application ports. A common usage is to access a web server hosted on the remote.

<figure><img src="/files/dV8lxxCW3WSUYtHN15t0" alt=""><figcaption><p>Accessing port 8100 on the remote server</p></figcaption></figure>


# Building Code from source

Building Code App from source is easy, thanks to Swift Package Manager for handling the dependencies.

### Environment requirement

* Xcode 13 or later
* An Apple ID if you want to install the app on a real device

### Building the project&#x20;

1. `git clone https://github.com/thebaselab/codeapp`
2. `./downloadFrameworks.sh`
3. Open Code.xcodeproj
4. Switch to CodeUI target if you wish to run the app on a simulator
5. Click build


# Frequently Asked Questions

### Local runtime

#### My favourite NPM / Python module doesn't work!

Many NPM / Python modules contain native components that need to be compiled when installing. These modules cannot be installed due to iOS's limitation. In addition, some modules only support desktop environment as some APIs are not available on iOS. However, you may create an issue if you want a specific module to be supported.

#### My PHP code is not running in the web privew.

The default web preview only serves static documents and does not run PHP code. To run a local PHP development server, run `php -S localhost:8000` in the terminal and visit localhost:8000 in Safari or other browsers.

### Server-side execution

#### What is server-side code execution and where do we host our server?

Server-side execution allows users to run simple programs in a large variety of programming languages. Our server is hosted on Google Cloud Platform and is based on an open source project called [judge0](https://github.com/judge0/judge0). Nothing is persisted and we don't store or access your code.

It comes with the purchase of the app as we don’t feel like a monthly subscription model suits the nature of development tools or competes with other existing services. That being said, we are shifting the focus of the app from remote to local execution. Currently, you can run Python, Node.js, PHP, C, C++ code locally. We are working on adding local support for more languages like Java.

### Version Control

#### I can't clone or push to a private repository.

You'll need to set your credentials at `Settings > Version Control > Authentication`. In many cases, you need to use a personal access token instead of the regular password. For GitHub, see <https://docs.github.com/en/github/authenticating-to-github/keeping-your-account-and-data-secure/creating-a-personal-access-token>

#### How to clone another repository?

You'll need to set the editor's root folder to another location. You can do this by selecting the configure folder tool located in file explorer. (Folder icon with a gear)

### Remote Connection

**I can't connect to a macOS Ventura SSH server using key authentication**

Currently, there is a compatibility issue with macOS Ventura and additional configuration is needed. Please refer to <https://github.com/thebaselab/codeapp/issues/715#issuecomment-1368351403>

### Others

#### How to change display language?

Go to iOS Settings App > Code and select a new language. Currently English, German, Korean and Chinese (*简化字)* are supported.

**I cannot access folders in OneDrive, Dropbox or other cloud providers**

Due to a limitation of Files App's API, it is only possible to access individual files (instead of the entire folder) in cloud providers. To access these files, use the `open file` function instead of `open folder`.


# Supported Languages

Here are the languages that you can run on Code App.

<table><thead><tr><th width="260.45648691938067">Language / Runtime</th><th width="150">Type</th><th>Extension</th></tr></thead><tbody><tr><td>Java (OpenJDK 8)</td><td>Local</td><td>.java</td></tr><tr><td>Python (3.9.2)</td><td>Local</td><td>.py</td></tr><tr><td>Node.js (16.13.2)</td><td>Local</td><td>.js</td></tr><tr><td>PHP (8.0.8)</td><td>Local</td><td>.php</td></tr><tr><td>C (Clang 13.0.0)</td><td>Local</td><td>.c</td></tr><tr><td>C++ (Clang 13.0.0)</td><td>Local</td><td>.cpp</td></tr><tr><td>Assembly (NASM 2.14.02)</td><td>Server-side</td><td>.asm</td></tr><tr><td>Basic (FBC 1.07.1)</td><td>Server-side</td><td>.bas</td></tr><tr><td>C (Clang 7.0.1)</td><td>Server-side</td><td>.c</td></tr><tr><td>C++ (Clang 7.0.1)</td><td>Server-side</td><td>.cpp</td></tr><tr><td>C (GCC 7.4.0)</td><td>Server-side</td><td>.c</td></tr><tr><td>C++ (GCC 7.4.0)</td><td>Server-side</td><td>.cpp</td></tr><tr><td>C (GCC 8.3.0)</td><td>Server-side</td><td>.c</td></tr><tr><td>C++ (GCC 8.3.0)</td><td>Server-side</td><td>.cpp</td></tr><tr><td>C (GCC 9.2.0)</td><td>Server-side</td><td>.c</td></tr><tr><td>C++ (GCC 9.2.0)</td><td>Server-side</td><td>.cpp</td></tr><tr><td>C# (Mono 6.6.0.161)</td><td>Server-side</td><td>.cs</td></tr><tr><td>COBOL (GnuCOBOL 2.2)</td><td>Server-side</td><td>.cob</td></tr><tr><td>Common Lisp (SBCL 2.0.0)</td><td>Server-side</td><td>.lsp</td></tr><tr><td>D (DMD 2.089.1)</td><td>Server-side</td><td>.di</td></tr><tr><td>Elixir (1.9.4)</td><td>Server-side</td><td>.ex</td></tr><tr><td>Erlang (OTP 22.2)</td><td>Server-side</td><td>.erl</td></tr><tr><td>Fortran (GFortran 9.2.0)</td><td>Server-side</td><td>.f90</td></tr><tr><td>Go (1.13.5)</td><td>Server-side</td><td>.go</td></tr><tr><td>Haskell (GHC 8.8.1)</td><td>Server-side</td><td>.hs</td></tr><tr><td>Java (OpenJDK 13.0.1)</td><td>Server-side</td><td>.java</td></tr><tr><td>JavaScript (Node.js 12.14.0)</td><td>Server-side</td><td>.js</td></tr><tr><td>Kotlin (1.3.70)</td><td>Server-side</td><td>.kt</td></tr><tr><td>Lua (5.3.5)</td><td>Server-side</td><td>.lua</td></tr><tr><td>Objective-C (Clang 7.0.1)</td><td>Server-side</td><td>.m</td></tr><tr><td>OCaml (4.09.0)</td><td>Server-side</td><td>.ml</td></tr><tr><td>Octave (5.1.0)</td><td>Server-side</td><td>.oct</td></tr><tr><td>Pascal (FPC 3.0.4)</td><td>Server-side</td><td>.pas</td></tr><tr><td>Prolog (GNU Prolog 1.4.5)</td><td>Server-side</td><td>.pl</td></tr><tr><td>R (4.0.0)</td><td>Server-side</td><td>.r</td></tr><tr><td>Ruby (2.7.0)</td><td>Server-side</td><td>.rb</td></tr><tr><td>Rust (1.40.0)</td><td>Server-side</td><td>.rs</td></tr><tr><td>Scala (2.13.2)</td><td>Server-side</td><td>.scala</td></tr><tr><td>SQL (SQLite 3.27.2)</td><td>Server-side</td><td>.sql</td></tr><tr><td>Swift (5.2.3)</td><td>Server-side</td><td>.swift</td></tr><tr><td>Visual Basic.Net (vbnc 0.0.0.5943)</td><td>Server-side</td><td>.vb</td></tr></tbody></table>