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.

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 providing the board type.

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 a board directory include:

  • upload;

    This 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.

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