Chapter 5. The Dno Directory System
Prev     Next

Chapter 5. The Dno Directory System

Each dno project must have its own set of directories. This section describes the organisation of a dno directory system.

5.1. The Project/Root Directory

This is the core of a dno project. The name of this directory is the name of the project. It can contain the following subdirectories:

  • board subdirectories;
  • library subdirectories;
  • a documentation subdirectory;
  • a tests subdirectory;
  • a build subdirectory;
  • a boot subdirectory.

It may also contain the following types of file:

  • sketch source code and header files;
  • a BOARD_TYPE file;
  • a BOARD_INFO file;
  • a BOARD_OPTIONS file.

This directory will normally only contain the various BOARD_XXX files and the build subdirectory if there are no board subdirectories.

For any project other than the smallest and simplest it is better to use board subdirectories and do all compilations there.

5.1.1.  Running dno in the Project/Root Directory

There are two significant, explicit dno targets that can be run in the Project/Root directory:

  • tests (aka test, unit, unit_test);

    Unit tests can be provided for libraries in explicit test directories. Running dno with an explicit "tests", "test", "unit" or "unit_test" target, will seek out those libraries that have unit tests, and run those unit tests, compiling and linking them first, if needed.

  • docs.

    The docs target attempts to build Doxygen documentation for the whole project.

Running dno without an explicit target in the project/root directory will perform different actions depending on circumstances.

5.1.1.1. With a BOARD_TYPE File

When a BOARD_TYPE file is present in the project directory, dno will attempt to compile and link your code, creating a build directory.

5.1.1.2. Without a BOARD_TYPE File

In the absence of a BOARD_TYPE file in the project directory, dno will not be able to build anything: 

blink$ dno
Nothing to be done here (in .../blink).
Try dno ./BOARD_TYPE or dno tests
blink$

5.2. Board Subdirectories

A board subdirectory is used as the home directory for builds for a specific board. The name of the directory provides the board type. This must be a unique board-specifier, but need not be completely specified.

Usually all sketch source and header files will be placed in the project root directory, however, if board-specific customisations are required, modified versions of source files can be placed in these directories. The local version of any file always takes precedence over the project directory's version.

5.2.1. Running dno in a Board Directory

Running dno without an explicit target in a board directory will compile and link any code that needs to be compiled/linked. As always, the object files, etc, will be created in a directory called build.

Explicit targets that you are likely to use in a board directory include:

  • upload and uploadp;

    These will attempt to upload the latest executable to a connected Arduino board. See Uploading To A Board.

  • eeprom.

    This will attempt to upload an eeprom image to a connected Arduino board. See EEPROMs.

5.3. Library Subdirectories

A library subdirectory contains the source code for a library. This may be a locally modified version of one of the standard libraries, or a fully custom library.

The distinguishing feature of a Library Subdirectory is that it will contain a source file with the same basename as that of the directory itself. Eg, if your library is named Deferal, there will be a source file called Deferal.cpp or Deferal.c.

Note that some libraries, generally those that contain a lot of code, may use an explicit src directory to contain the source code.

5.3.1. Running dno in a Library Directory

Running dno without an explicit target in a library subdirectory will attempt to build and run any unit tests that been have defined. See Unit Testing With Dno.

If no unit tests have been defined, dno will warn the user and then do nothing.

The only significant explicit target that makes sense to use in a library subdirectory is docs. You can also use test, tests, unit or unit_test but since these do the same as the implicit target, there is little point. The docs target will attempt to create stand-alone documentation for the library using Doxygen.

5.4. The docs Subdirectory

The docs subdirectory is where Doxygen-based documentation will be prepared. Documentation created here will be for everything within the project, and will include libraries, even if those libraries have their own separate library specific documentation.

This is covered in detail in Documentation with Doxygen.

Note that individual libraries may also contain docs directories. These are for library-specific documentation.

5.4.1.  Running dno in a docs Directory

The only target that makes sense in the docs subdirectory is the docs target. Running dno without an explicit target will do exactly the same thing.

5.5. The boot Subdirectory

A board directory, or the root directory if it identifies a BOARD_TYPE may contain a boot subdirectory. This is where code for a bootloader can be built.

Bootloaders are able to change the standard on-boot behaviour of an Arduino board. For example optiboot is a bootloader that allows the Arduino to boot without an initial delay. This can be very useful for some applications.

Dno does not really know how to build bootloader code. It expects bootloader code to be built using make, and running dno in a boot directory will, by default, simply result in make being invoked.

If more sophisticated behaviour is required a dno.mk file can be added to the directory to provide specific build instructions.

Prev     Next
Chapter 4. A Little Exploration  Home  Chapter 6. Libraries