Desktop Development Environment Examples
========================================
This file describes the contents of the Sources.DDE-Examples directory from the
Desktop Development Environment.

In this release of the DDE, all the example makefiles have been updated to make
use of the shared makefiles used to build RISC OS. This simplifies the
makefiles considerably, and we would strongly recommend using this approach
instead of using the old !Make tool, although this is still provided.

Each example that has a makefile can be built by double-clicking on the 'Mk' or
'MkInstall' file and cleaned by double-clicking on the 'MkClean' file. For the
examples that have 'MkInstall' files, the resulting application will be
installed in the directory defined by the <Install$Dir> variable. By default
!SetPaths sets this to "AcornC/C++.Install".

ABC
===
This directory contains the examples for the Archimedes BASIC Compiler which
are referred to in the accompanying manual.

C/C++
=====
This directory contains some simple examples that illustrate the use of the
Desktop C/C++ tools. An overview can be found at the end of Chapter 1 of the
C/C++ manual in the "Worked Examples" section.

  CHello & C++Hello
  -----------------
  These are "Hello World" programs that show the basic use of the compiler.
  They are described in the "Getting started with CC and C++" section of
  Chapter 11 ofthe C/C++ manual.

  CError & C++Error
  -----------------
  These are versions of the "Hello World" programs that contain errors. They
  are described in the "Throwback" section of Chapter 5 in the Desktop Tools
  manual.

  Sieve
  -----
  An example implementing The Sieve of Eratosthenes.

  Dhrystone
  ---------
  The Dhrystone 2.1 benchmark. Illustrates the use of the shared makefiles.

  CModule
  -------
  An example of how to implement a RISC OS relocatable module in C, and how to
  use the shared makefiles to build a module. See the "Worked Examples" section
  of the C/C++ manual for more information.

Debug
=====
The "Sort" example in this directory illustrates the use of the Desktop
Debugging Tool (DDT). See the section "An example debugging session" at the
end of Chapter 3 of the Desktop Tools manual.

ObjAsm
======
The examples in this directory illustrate the use of the ObjAsm assembler. They
are mostly described in the ObjAsm manual.

  AsmError
  --------
  A "Hello World" program that contains an error. It is described in the
  "Throwback" section of Chapter 5 in the Desktop Tools manual.

  AsmHdrs
  -------
  Contains header files used by the other examples.

  AsmHello
  --------
  A "Hello World" program written in assembler. It is used in the "Example
  ObjAsm session" section of Chapter 1 in the ObjAsm manual.

  AsmMacro
  --------
  An ObjAsm macro for integer division. See Chapter 9 of the ObjAsm manual.

  AsmModule
  ---------
  An example of how to implement a RISC OS relocatable module in assembler.
  See Chapter 11 of the ObjAsm manual.

  PrintLib and CStatics
  ---------------------
  These examples show how to interwork assembly language and C. They are
  described in Chapter 12 of the ObjAsm manual. PrintLib is also used as an
  example for the LibFile tool in Chapter 13 of the Desktop Tools manual.

Toolbox
=======
The examples in this directory are all Desktop applications illustrating the
use of the Toolbox. Each application can be built by double-clicking on the
'MkInstall' file and will be installed in the directory defined by the
<Install$Dir> variable. By default !SetPaths sets this to "AcornC/C++.Install".

  MinApp
  ------
  A minimal Toolbox application.

  Hyper
  -----
  A HyperCard viewer application. This example is described in detail in
  Chapter 2 of the Toolbox manual.

  SaveAs1, SaveAs2 and SaveAs3
  ----------------------------
  Examples of the three different ways that the SaveAs Dialogue box class can
  be used. Refer to Chapter 14 of the Toolbox manual for more information.

  TboxCalc
  --------
  A simple calculator application, implemented using the Toolbox.

Skeletons
=========

These example programs have been written to illustrate how you could
structure your source code when building a number of different types of RISC
OS software, in a number of languages. They take full advantage of the
facilities in the broader RISC OS build environment, including the shared
makefiles, which help to greatly simplify the makefile for the average
component.

The example programs included here are:

  exampleabs    - an 'Absolute' file (standalone executable) in C
  exampleabsasm - an 'Absolute' file, in ARM assembly
  exampleabsc++ - an 'Absolute' file, in C++
  exampleapp    - the very basics of a RISC OS application, in C
  examplelib    - a static library, in C
  examplemod    - a relocatable module in C
  examplemodasm - a relocatable module, in ARM assembly
  exampleutil   - a 'Utility' file (very lightweight executable), in ARM

It is intended that these are used in conjunction with a RISC OS build
environment, you can download some pre-built environments from the "Source
code archives" section of this page:

  https://www.riscosopen.org/content/downloads/risc-os-tarballs

We would suggest downloading the "DiscDev" build as a good starting point
you should use the Utilities.!UnTarBZ2 application to decompress the source
code archive.

See our instructions here for more information:

  https://www.riscosopen.org/wiki/documentation/show/Technical%20notes

SID
===

Some examples to exercise and demonstrate the $.Apps.DDE.!SID application,
which can be used to disassemble compiled/assembled code into more human-
readable ARM code.

  Binary.warnings - run this through SID to get some examples of the sort
                    of warnings it can flag up
  s.warnings      - this is the sort of thing you should expect to see when
                    the "warnings" binary is run through SID
  Offsets         - includes a couple of 'offsets' files which SID uses to
                    customise its interpretation of the input file
     SID/SOF      - use this to help disassemble the "!SID.Bin.SOF" file
     ReplayCodec  - use this to help disassemble Acorn Replay codec files

See: $.Documents.DDE.SID for more information.
