Skip to main content

Setup

Just want to use the library?

If you only want to use Img2Num (e.g. via npm), see the relevant documentation from the links below instead.

This page explains how to build the project for development.

C

C++

JavaScript

Python

0. Before you begin​

Planning to contribute?

If you intend to contribute to Img2Num, fork the repository first and clone your fork instead of the main repository.

If you're only experimenting with the codebase or building the project locally, you can clone the main repository directly.

The complete contribution workflow is explained in the Pull Requests guide.

0.1. Prerequisites​

Verify Prerequisite Installations:

Paste this in your terminal
git --version
docker --version
Docker

We recommend using our prebuilt Docker dev environment. Setting up the environment locally adds unnecessary complexity, so we recommend against it.

If you choose to develop locally, you are responsible for configuring and maintaining your own environment.

0.2. Quick Start​

This section will help you get started quickly so you don't have to read everything below.

Clone and setup​

Paste this in your terminal
# Clone the repository
git clone https://github.com/<your-username>/Img2Num.git
cd Img2Num/

# Open Docker container
./img2num sh

# Initialize and build the project
just init

Test that everything works​

See Test that everything works below.

See the other documentation​

We recommend that you read the documentation below as well as the Docker Script and Just pages to understand how the development environment works.

1. Clone the repository​

Paste this in your terminal
git clone https://github.com/<your-username>/Img2Num.git
cd Img2Num/
Don't recurse submodules

Recursing all Git submodules (especially Dawn's) can be very slow and takes up a lot of space. We don't recommend worrying about them at this stage - Step 3 will handle it for you.

just init (in Step 3) will pull and manage the submodules automatically for you.

2. Start the dev container​

The command below opens the Docker development container's Bash shell. The img2num script manages the container.

Paste this in your terminal
./img2num sh

See the Img2Num Docker Script page for more information about this.

3. Initialise and build everything​

Img2Num uses Just to make it easier to manage the repository. It allows us to consolidate our scripting with a single tool.

The purpose of the command below is to give you a clean, working checkout. You won't need to use it again.

Paste this in the Docker shell
just init

As mentioned in Step 1 just init:

  1. Installs dependencies (shallow Git submodule pull, pnpm install, etc.)
  2. Compiles all code (C++, C, JavaScript, Python package, etc.) via just build all.

See Img2Num's Just documentation page for more information.

4. Test that everything works​

Input Image

Ensure that you have an image to test with.

We recommend using a small image to do the testing because they are fast to process.

Picsum Photos offers some nice random images:

To test that you have built everything properly, we recommend running just build all from above and testing each example app. You can find out how to use the example app on our Just documentation page.

DONE!​

Congrats! You're now good to go.

Next Steps

You'll probably want to check out one of these sections next, though:

  • Building the project
  • Cleaning the project
  • What to do when you forget a command