C/C++ Building Environment

From Black Swift
Jump to: navigation, search

C and C++ are definitely the most powerful languages you can choose to create programs for Black Swift - with low-level access to hardware resource you'll be able do do a lot of things unavailable in most high-level languages.

But, unlike Perl or Python, C/C++ programs must be compiled before uploading to Black Swift - and as Black Swift offers a very specific environment (MIPS CPU architecture and OpenWRT OS), you have to install and configure special building environment to be able to compile Black Swift programs on your PC or laptop.

Using 64-bit Linux PC

Official OpenWRT way to compile C/C++ programs is to use 64-bit Linux machine.

  • Download OpenWRT SDK for ar71xx architecture and extract it to a folder
  • Install additional packages (depend on Linux distro you are using, but the usual way is to try to build something and see if any package is missing)
  • ?????
  • PROFIT!!!

Using 32-bit Linux PC

There are a lot of people using Linux on old machines with 32-bit CPUs - as home routers, NASes or just because it's a good way to utilize old PC. Unfortunately, official OpenWRT SDK is for 64-bit CPUs only. That's why we prepared 32-bit SDK - download it here.

Otherwise, there's no difference between working on 32-bit or 64-bit machine.

Using Windows or Mac PC

There are way more people who don't have Linux at all. For them we created minimal Linux distribution (including all tools you need and OpenWRT SDK unpacked) to run in Oracle VirtualBox. Still, to use it you will need basic Linux knowledge - how to work with command prompt, files, etc.


  • Download Oracle VirtualBox here (it's free)
  • Download our VirtualBox HDD image (ZIP file).
  • Unpack HDD image (final size will be around 2 GB)
  • Install and run Virtual Box
  • Create new virtual machine for 32-bit Linux with 1024 MB RAM, make sure PAE is enabled in VM's CPU configuration
  • When asked about virtual disk image, choose to use existing image and point VirtualBox tho the VDI file you already downloaded and unpacked
  • Configure VM's networking in VirtualBox - usually bridge mode is the best
  • Start VM

You will be logged in automatically under "openwrt" login. Root password is "openwrt", openwrt password is "openwrt" as well. OpenWRT SDK is waiting for you in the /home/openwrt/Openwrt-SDK-BB folder.

Creating OpenWRT Makefile

Inside OpenWRT SDK folder, packages to compile are stored in the packages/ subfolder, each project in its own folder. But usually there's no source code - just an OpenWRT-specific file named Makefile and sometimes patches/ subdirectory. It was made to avoid distributing every package with OpenWRT itself - Makefile contains instruction on how to download, unpack and compile corresponding package automatically, for example, from GitHub or SourceForge.

Your first program probably shouldn't be uploaded anywhere yet, and in any case it's usually simpler to build and test programs locally before uploading them. There's a nice guide to using Makefiles on official OpenWRT website, but here we will provide a simple Makefile example to compile local sources.

Let's create directories first:

Project folder: packages/myproject
Project sources: packages/myproject/src
OpenWRT Makefile: packages/myproject/Makefile

Please note that project sources must contain another Makefile - with regular instructions on how to compile the program with GCC. It's a regular Makefile, not specific to OpenWRT.

Let's create packages/myproject/Makefile:

include $(TOPDIR)/rules.mk

# Your program's name, package version and release number
PKG_NAME:=myproject
PKG_VERSION:=0.0.1
PKG_RELEASE:=1

# Setting the standard path where to build it.
# Nothing to change here actually.
PKG_BUILD_DIR:=$(BUILD_DIR)/$(PKG_NAME)
include $(INCLUDE_DIR)/package.mk

# Package description
define Package/myproject
    # Section and category in OpenWRT's package hierarchy
    SECTION:=base
    CATEGORY:=Utilities
    # Should it be built by default?
    DEFAULT:=n
    # Package title
    TITLE:=This is my first project
    # Package URL
    URL:=http://black-swift.com
    # Other packages your program needs (our doesn't need anything, so let's comment it out)
    # DEPENDS:=+libstdcpp
endef

# Long description, you can put a few lines of text here
define Package/myproject/description
    This! Is! My! First! Project!
endef

# What OpenWRT SDK should do before compiling the package
# 1. Create building directory
# 2. Copy package sources to it (in our case - from the src/ directory)
define Build/Prepare
    mkdir -p $(PKG_BUILD_DIR)
    $(CP) ./src/* $(PKG_BUILD_DIR)/
endef

# Building the package, nothing actually to change here now
define Build/Configure
    $(call Build/Configure/Default,--with-linux-headers=$(LINUX_DIR))
endef

# Package installation
# 1. Specify the destination directory (on Black Swift, not your PC; will be created if doesn't exists yet)
# 2. Copy executable files to it
# If you have more than one executable in you program - list them one by one
define Package/treelights/install
    $(INSTALL_DIR) $(1)/usr/bin
    $(INSTALL_BIN) $(PKG_BUILD_DIR)/myproject $(1)/usr/bin/
endef

$(eval $(call BuildPackage, myproject))

Compiling the program

If your program depends on some other utilities or libraries - download them first, unpack to packages/ directory and compile.

Compiling your program is easy (project folder is packages/myproject/, sources is in packages/myprojecr/src/, OpenWRT Makefile is packages/myproject/Makefile):

make packages/myproject/{clean,compile} V=s

If everything is ok, now you have myproject_0.0.1-1_ar71xx.ipk in the bin/ar71xx/packages/base/ folder. This is your program ready to be installed on Black Swift.

Working with patches

Sometimes you need not to write a program from the scratch, but change something in already existing package. It is should be done with patches - files describing the difference between your version and original package.

There's an excellent step-by-step guide on working with patches on official OpenWRT website.

Installing the program on Black Swift

After compiling your program you need to copy it to the Black Swift - there are a lot of ways available, including copying over SSH (e.g. with WinSCP), uploading from Black Swift's command line with wget or even using USB flash drive.

To install program, run (in the Black Swift shell):

opkg install myproject_0.0.1-1_ar71xx.ipk

To remove it, run:

opkg remove myproject