0%

Build

All Cogent Core apps can be built using normal go commands (go build, go run, go install, etc). This means that things such as tests, debuggers, and race detectors work as usual.

However, the Cogent Core command line tool core provides a build process optimized for cross-platform Cogent Core development. This tool automatically sets appropriate linker flags to reduce binary sizes, optimizes binaries for running as standalone GUI apps, and provides support for building for mobile and web platforms.

The core command line tool provides four main build commands, as documented below. In general, you should use core run during development.

  1. 1. 

    core build builds a standalone binary executable for the app

  2. 2. 

    core run builds a standalone binary executable for the app and then runs it on the target device

  3. 3. 

    core pack packages the app into a self-contained package and builds an installer for it

  4. 4. 

    core install installs the app on the target system

You can build for mobile and web platforms by adding the platform name after the command. For example, you can run core run android to build and run an app on an Android device, core build ios to build an app for an iOS device, and core run wasm to serve an app on the web.

There are two web platforms: wasm compiles the app to WebAssembly, and js compiles it to JavaScript with GoScript. The js platform installs GoScript and bun automatically if they are not already installed. We recommend js, which is what this website uses.

Note: core run wasm and core run js are mainly used for serving an app locally for testing; to deploy an app on the web, you can use core build wasm or core build js and a static site host (here is an example using GitHub Pages).

If there is an icon.svg file in the current directory, it will be used as the app icon on all platforms.

The core command also builds the icon into the app, as core.AppIcon, which is the icon of its windows, and on macOS its icon in the Dock while it runs. go build and go install do not, so an app built with them has the default Cogent Core icon in its windows, and keeps the icon of its app bundle in the Dock, as for an app installed with AppGoSymlink (see below). To have the icon of the app either way, embed icon.svg in the main package and set it at the start of main:

//go:embed icon.svg
var appIcon string

func main() {
	core.AppIcon = appIcon
	...
}

For the setup for building for iOS and Android, and running apps in their simulators, see Mobile below.

Mobile

You can build for Android on all desktop platforms, and for iOS on macOS only. The ID in the core.toml of the app (such as com.cogent.lists) is its bundle ID on iOS and its package name on Android. It must be the same in every build, so that a new build replaces the installed app and keeps its data.

iOS

For iOS, you need Xcode (the full app, not only its command line tools that core setup installs), with the iOS platform installed in its settings (Components). Xcode includes the iOS simulator, so nothing else is needed for it.

core run iossimulator builds the app for the iOS simulator and runs it there: in a simulator device that is booted, or else it boots the newest iPhone and opens the Simulator app to show it. Add -d to see the output of the app in the terminal. The app is built with the iossimulator build tag, which selects the WebGPU library for the simulator; that needs version 1.38.0 or later of github.com/oliverbestmann/webgpu in the go.mod of the app. core build iossimulator only builds it.

For an iPhone or iPad, the app must be signed: sign in to your Apple account in Xcode (Settings, Accounts), which makes an “Apple Development” certificate, from which core build ios gets the ID of your team. On the device, turn on Developer Mode (Settings, Privacy & Security), connect it with a cable (or on the same network, once it is paired in Xcode), and trust the computer. core install ios installs the app with ios-deploy (brew install ios-deploy), as does core run ios, which can not start it without the debugger: core run ios -d also starts it, with its output in the terminal. The first time, you may need to trust your developer certificate on the device (Settings, General, VPN & Device Management).

Android

For Android, you need the Android SDK, with its NDK (for building) and its platform tools (adb, for installing apps). core setup -androidsim installs all of that, without Android Studio, together with the Android emulator:

core setup -androidsim

It installs the SDK in the standard place (~/Library/Android/sdk on macOS, ~/Android/Sdk on Linux, and %LOCALAPPDATA%\Android\sdk on Windows), or in ANDROID_HOME if that is set, where Android Studio also finds it, and it uses what is there already, so it also updates an existing SDK. It installs the command line tools of the SDK if they are not there, which need Java (a JDK of version 17 or later; on macOS, it installs the openjdk of Homebrew if there is none), then accepts the licenses of the SDK, and installs the platform tools, the emulator, a system image of the emulator for the architecture of the computer (arm64 on Apple silicon), and an NDK if there is none. Then it makes an Android virtual device for the emulator, named Cogent, with the keyboard of the computer enabled.

core run android runs the app on an Android device that is connected (with USB debugging, below), or else it boots the emulator with the Cogent virtual device (or the first one, if there is no Cogent one), which keeps running after that, for the next runs. It builds the app only for the architecture of the device, which is faster than core build android, which builds it for all of them. When there are several devices, such as the emulator and a phone, it uses the phone, and says so; set ANDROID_SERIAL to the serial of another one (from adb devices) to use it instead. Add -d to see the output of the app (adb logcat, which core log also shows).

For an Android phone or tablet, turn on its developer options (tap Build number seven times in Settings, About phone), then turn on USB debugging in them, and connect it with a cable. Accept the prompt on the device to allow USB debugging from the computer; until then, adb devices lists it as unauthorized, and core run android says so and uses the emulator instead.

Apps target Android 15 (API level 35) by default (AndroidTargetSDK in the [Build] section of core.toml; AndroidMinSDK is 23), so that current versions of Android do not warn that they are out of date, and they are drawn edge to edge, behind the system bars, which are filled with the background of the app. The APK is signed with both the v1 (JAR) and v2 APK signature schemes, which newer versions of Android require, and its native libraries are aligned for devices with 16 KB memory pages.

On Android, the back button or gesture of the system goes back within the app, as the back button of the top bar of a full-window stage does, and closes a dialog or popup menu; it leaves the app only when there is nothing to go back to.

Mobile apps

An app runs the same on mobile platforms as on desktop ones, but it should adapt to small screens, touch, and the virtual keyboard. Cogent Lists is a prototype of how to specialize the functionality and flow of an app for mobile while sharing as much code as possible with its desktop version:

  • • 

    The app is a package (lists) with a Mobile setting, and two small main packages: cmd/lists for desktop platforms and cmd/mobile for mobile platforms (with its own core.toml), which also runs on desktop platforms, for trying the mobile layout there. All of the rest is shared, and the mobile layout only changes how the same widgets are arranged.

  • • 

    On desktop, the tree of lists, the items of the current list, and the form of an item are panels side by side. On mobile, each is in a full window, in turn (a full-window stage with a back button, which the Android back button also uses), and the table of the items shows only the main fields, with a button that opens the form of an item with all of them.

  • • 

    The tools that are in the top toolbar on desktop are at the bottom on mobile, where they are easy to reach, with the less common ones in its overflow menu.

  • • 

    Selecting several items, which takes Shift or Command with a mouse, is a select mode on mobile (“Select items”), in which taps select items without starting to edit them.

  • • 

    Edits are saved as soon as they are made, and synced right away on mobile, as an app is often closed just after it is used. When the app goes into the background, the edit in progress is completed, as when the focus leaves it, and system.App.BeginBackgroundTask asks the system to keep the app running for a while to finish the sync (on iOS; on Android, apps keep running for a while in the background anyway).

The app is laid out above the virtual keyboard while it is shown, and the focused widget is scrolled into view, so a text field that is edited is never under the keyboard. The return key of the keyboard (Done) works as Enter, completing the edit.

Web index page

When building for web, the core tool generates an index.html file that loads the app. While the app is loading, it shows a preview of the app, which is automatically pre-rendered as HTML at build time. This preview is also what search engines and social media sites see.

You can replace that automatic preview with your own content by making an index.html or index.md file (converted from markdown) in your app directory. If both exist, index.html is used. These files specify the body content, and are imported within a page that loads the app and sets default styles. Do not include <html>, <head>, or <body> elements.

You can include a <script> element in your index page, and it will run, but note that the entire loader element is removed as soon as the app finishes its first render. Anything that the script registered, such as a timer or an event listener, keeps running after that, so it must clean up after itself.

Content websites

For apps that use content, each content page is pre-rendered as its own HTML page, along with navigation trees for the table of contents and categories and a page search, which use Vue.js and closely replicate the content app. Math is rendered with KaTeX. Code blocks are shown with syntax highlighting, but interactive Go examples are not run, so their resulting widgets are not shown. Any non-page files in the content directory, such as images, are copied into the website. These pages are shown while the app is loading, and they are what search engines see.

You can also build a freestanding website that consists only of these static HTML pages, without the Go wasm app, using core build wasm -htmlonly. The pages are the same, except that they do not load the app.

Code blocks of content apps

In a content app, a Go (or Goal ) code block in a page is an interactive example: the page shows the code in a text editor and runs it, showing the widgets that it makes below it. core build, core run, core install, core pack, and core generate compile these code blocks into the app: they write a contentcode_gen.go file to the main package of the app with a Go function for each code block, and the page runs that function directly, without an interpreter, on all platforms (on js, GoScript compiles it with the rest of the app). This is faster, and the code blocks are type checked at build time.

This happens automatically for any main package that imports the content package and embeds a directory of markdown files. The generated file records a hash of the code blocks, the options, and the go.mod file of the app, and nothing is done if that hash has not changed, so this only takes time (a few seconds) after you change a code block. You should commit the generated file, so that go build and go run also work.

Code blocks are written as before: a list of statements that use the parent widget b and the Cogent Core packages without importing them, or a program with a main function. Unused variables are allowed. A code block that does not compile is left out and listed at the end of the generated file, and the command prints its errors at their place in the markdown file (such as content/button.md:15:25: undefined: x). The code blocks can only be compiled if the rest of the app compiles, so core generate fails with the errors of the app if it does not.

When someone edits a code block, the edited code runs in the mvm Go interpreter if the app includes it, by importing cogentcore.org/core/mvmcore; otherwise, edited code can not run. On the js platform, you can load the interpreter only when code is first edited, so that it does not slow down the startup of the app: instead of importing mvmcore for its side effects, set content.BindTextEditor = mvmcore.BindTextEditor in an init function of the app, and add DeferredFunctions = ["cogentcore.org/core/mvmcore.BindTextEditor"] to the [Web] section of core.toml. This website does that.

Goal code blocks

Goal code blocks, written in Goal, are compiled too, if the module of the app requires Cogent Lab, whose Goal transpiler turns them into Go (otherwise, the command says so, and they run in the Goal interpreter, if the app includes it). As in the Goal interpreter, the Goal code blocks of a page run in order and share their variables: a block can use the variables and functions of the blocks before it on its page. Goal code can use the Cogent Lab packages (tensor, plot, matrix, …) without importing them. A page is compiled up to its first Goal code block that does not compile; that block and the ones after it run in the Goal interpreter, if the app includes it.

The Goal interpreter of edited code is mvmlab.BindTextEditor (cogentcore.org/lab/mvmlab), or that of another package that adds more symbols to it. As for Go, set content.BindTextEditor to it in an init function and add it to DeferredFunctions in the [Web] section of core.toml (for example DeferredFunctions = ["cogentcore.org/lab/mvmlab.BindTextEditor"]), so that js builds load it when code is first edited.

Options

Options for compiling code blocks go in the [ContentCode] section of core.toml:

[ContentCode]
  # other packages that code blocks use without importing them (path or name=path)
  Imports = ["github.com/me/sim/wavesim"]
  # whether Goal math mode records its variables in tensorfs, as mvmlab does
  # (on by default; turn it off if the Goal interpreter of the app does not)
  GoalRecord = false
  # pages whose code blocks run in the interpreter instead of being compiled
  # (markdown files in the content directory, with or without .md; wildcards ok)
  Interpret = ["channel-plots"]

Code that few pages use, such as that of interactive plots on one page, can be kept out of the startup of a js app with Interpret: the code blocks of those pages are not compiled into the app, so they run in the interpreter, which is then loaded (as a deferred function, with the packages that the code uses) only when one of those pages is shown.

If you prefer go generate, you can add //go:generate go run cogentcore.org/core/content/cmd/contentcode to the main package of the app instead; the core tool then uses the same arguments (such as -o for the output file, -import name=path for other packages that code blocks use without importing them, -interpret page for pages whose code blocks run in the interpreter, or -goal-record=false), together with the options of core.toml.

Details

Cross-compiling between desktop platforms is planned but not yet supported (see Mobile for the mobile platforms).

The file(s) produced by core build are .exe on Windows, .app on iOS, .apk on Android, .wasm (or .js for js) and associated .html and .js files on the web, and no extension on macOS and Linux. The file(s) are placed in the current directory for desktop platforms, and bin/{platform} for other platforms (eg: bin/android).

For desktop platforms, core run just runs the executable directly. For mobile platforms, it installs the executable package on the target device (which can be a simulator or a real connected device) using core install and then starts it. For js and wasm, it serves the files in bin/js or bin/wasm at http://localhost:8080.

On mobile and web platforms, core pack is the same as core build, as that already makes a package on those platforms. On macOS, it makes a .app bundle file and a .dmg disk image installer file. On Windows, it makes a .exe installer file. On Linux, it makes a .deb package file.

For macOS, core install means running core pack and then copying the resulting .app file to Applications. It is not yet implemented on Linux and Windows. For mobile platforms, it installs the executable package on the target device, which can be a simulator or a real connected device. For web, it is not applicable.

For an app that is updated often, AppGoSymlink = true in its core.toml makes core install on macOS also install it with go install, and make the executable of the app in Applications a symbolic link to that one, so that go install is enough to update the app after that.

Settings like this one are often your own, not those of the project, so the core command also reads a core.toml of yours for all projects, before the core.toml of the project, which overrides it: ~/Library/Cogent Core/core.toml on macOS, ~/.config/Cogent Core/core.toml on Linux, and AppData/Roaming/Cogent Core/core.toml in your home directory on Windows. For example, with AppGoSymlink = true in it, core install makes the symbolic link for all of your apps, except those with AppGoSymlink = false in their core.toml.

Opens in the core.toml of an app lists the types of files that it opens, which core pack and core install declare, so that the system offers the app in its “Open with” choices for those files, without making it their default app: categories of files (such as Code or Text) or known types of files (such as Markdown or TeX), as in base/fileinfo. For example, Cogent Code has Opens = ["Code", "Text", "Markdown", "TeX"] (and more). The app gets the files to open as events.OSOpenFiles events, or as arguments on Linux.

To silence this annoying warning on Mac: ld: warning: ignoring duplicate libraries: '-lobjc' do this in the terminal:

go env -w CGO_LDFLAGS="-O2 -g -Wl,-no_warn_duplicate_libraries"