O2 SDK V1.03
                         http://www.cowon.com (Korean)
                     http://www.cowonglobal.com (English)


##############################################################################
#                                  Contents                                  #
##############################################################################
1.  Introduction
  1.1  What is COWON O2 SDK?
  1.2  Directory Structure
  1.3  Linux User
  1.4  Windows User

2.  HOW-TO Build and Compile
  2.1  Configure Options
  2.2  HOW-TO Build and Compile on Linux
  2.3  HOW-TO Build and Compile on Cygwin

3.  HOW-TO Start New Project (example)
  3.1  Create Project Directory
  3.2  Create a source file for new project
  3.3  Create 'Makefile.am' in your new project directory
  3.4  Modify 'configure.ac' in 'O2_SDK_V1_03/src' directory
  3.5  Modify 'Makefile.am' in 'O2_SDK_V1_03/src' directory
  3.6  Re-create 'configure'
  3.7  Configure
  3.8  Build and Compile
  3.9  Run an example program on Linux or Cygwin
  3.10 Run an example program on O2PMP

Appendix  A.
  A.1  What is X11?
  A.2  What is Cygwin?

Appendix  B.
  B.1  HOW-TO Install gcc libraries on Linux (Ubuntu)
  B.2  HOW-TO Install X11 libraries on Linux (Ubuntu)
  B.3  HOW-TO Install autoconf on Linux (Ubuntu)
  B.4  HOW-TO Install automake on Linux (Ubuntu)




1. Introduction

  This document introduces the definition and the structure of COWON O2 SDK and
  describes the way how to build and compile on Linux and Cygwin.

  In addition it explains a method of starting a new project with an example.

  Therefore users(application programmers) can make easily their own 'USER PROGRAMS'.


  1.1 What is COWON O2 SDK(Software Development Kit)?

    COWON O2 SDK is a set of development tools that
    allows users(software engineers) to create applications for COWON O2PMP.


  1.2 Directory Structure

    O2_SDK_V1_03 +-- src +-- cowon_lib
                 |       |
                 |       +-- cowon_x11_lib
                 |       |
                 |       +-- sample1
                 |       |
                 |       +-- sample2
                 |       |
                 |       +-- stopwatch
                 |
                 +-- toolchain +-- cygwin_toolchain
                               |
                               +-- linux_toolchain

    O2_SDK_V1_03/src/
      - Contains COWON O2 libraries for development of user programs and sample programs

    O2_SDK_V1_03/src/cowon_lib/
      - Contains essential COWON O2 libraries for development of user programs on O2PMP

    O2_SDK_V1_03/src/cowon_x11_lib/
      - Contains essential COWON O2 libraries for development of user programs on O2PMP
      - It is referenced when you build and compile in X11 environment.

    O2_SDK_V1_03/src/sample1/
    O2_SDK_V1_03/src/sample2/
    O2_SDK_V1_03/src/stopwatch/
      - Contains source of sample programs

    O2_SDK_V1_03/toolchain
      - Contains ARM tool chains for Linux and Cygwin

    O2_SDK_V1_03/toolchain/cygwin_toolchain
      - Contains ARM tool chain for Cygwin

    O2_SDK_V1_03/toolchain/linux_toolchain
      - Contains ARM tool chain for Linux


  1.3 Linux User

    If you have a Linux-installed computer,
    You can build and compile sample programs within the released SDK and your source files.

    Moreover the SDK supports the development environment with X11
    so that you can run your program on Linux and debug it easily using debugging tools
    such as GDB.

    More information on Section 2.2.


  1.4 Windows User

    Even if you don't have a Linux-installed computer,
    you can build and compile them by using Cygwin,
    which is an amulator supporting Linux-like environment for Windows.

    More information on Section 2.3.


2. HOW-TO Build and Compile

  2.1 Configuration Options

    2.1.1 '--host' option

      This option is used in order to build cross compilation for running applications
      in O2PMP.

      e.g. --host=arm-linux


    2.1.2 '--with-run-env' option

      This option is used in order to determine a running environment (X11 or O2PMP).

      e.g. --with-run-env=x11
           --with-run-env=o2pmp   (default)


    2.1.3 '--with-x11-path' option

      This option is used in order to direct the path of X11 libraries.

      e.g. --with-x11-path=/usr/X11R6/lib

      If you do not know the path of X11 libraries,
      you will be able to find the path by using command below.

      # find / -name "libX11.*"

      The result messages MUST include 'libX11.so' and 'libX11.a' files.

      Otherwise you MUST install X11 libraries. (ref. Appendix B)


    2.1.4 '--with-tool chain-path' option

      This option is used in order to direct the path of ARM tool chain.

      e.g. --with-toolchain-path=/usr/local/toolchain
           --with-toolchain-path=[...]/O2_SDK_V1_03/toolchain/linux_toolchain    (default)
           --with-toolchain-path=[...]/O2_SDK_V1_03/toolchain/cygwin_toolchain   (default)


  2.2 HOW-TO Build and Compile on Linux

    (1) Copy the compressed SDK file(O2_SDK_V1_03.tar.bz2) to a directory
    (2) Decompress the file
    (3) Move to 'O2_SDK_V1_03/src/' directory
    (4) Do 'configure'
    (5) Do 'make'
    (6) Run

    ===============================================================
    # ls
    O2_SDK_V1_03.tar.bz2

    # tar xfj O2_SDK_V1_03.tar.bz2

    # ls
    O2_SDK_V1_03    O2_SDK_V1_03.tar.bz2

    # cd O2_SDK_V1_03/src/
    ===============================================================


    2.2.1 X11

      X11 libraries MUST be installed in your Linux PC.
      Otherwise sample programs and other user programs DO NOT work properly.

      If X11 libraries are NOT installed, reference Appendix B.

      # ./configure --with-run-env=x11

      If you fail the above command, try again with '--with-x11-path' option as follows.
      # ./configure --with-run-env=x11 --with-x11-path=[X11 libraries path]

      # make

      Run sample1
      # cd sample1
      # ./sample1.o2

      Run sample2
      # cd sample2
      # ./sample2.o2

      Run stopwatch
      # cd stopwatch
      # ./STOPWATCH_V1.o2

      You MUST run a sample program as root because it controls soundcard device drivers,
      which need root permission, for playing wav files.


    2.2.2 O2PMP

      # make clean
      # ./configure --host=arm-linux
      # make

      In order to run sample programs on O2PMP, connect O2PMP to your PC via USB cable.

      And copy the generated file, 'sample1.o2', 'sample2.o2', or 'STOPWATCH_V1.o2',
      to the directory, 'USRPROG', in the O2PMP device with a related folder
      that are needed for execution such as 'sample1/', 'sample2/' or 'stopwatch/' folder.

      Reboot and click 'usrprog' icon in UTILITIES menu and run the .o2 file.


  2.3 HOW-TO Build and Compile on Cygwin

    When installing Cygwin, you MUST select 'All-Install' option.

    If you install with 'All-Default' option,
    You wonĄŻt be able to built and compile O2 sample programs and other programs you made.

    (1) Copy the compressed SDK file(O2_SDK_V1_03.tar.bz2) to '/' directory (C:\cygwin\)
    (2) Decompress the file
    (3) Move to 'O2_SDK_V1_03/src/' directory
    (4) Commend 'configure'
    (5) Commend 'make'
    (6) Run

    ===============================================================
    # ls
    O2_SDK_V1_03.tar.bz2

    # tar xfj O2_SDK_V1_03.tar.bz2

    # ls
    O2_SDK_V1_03    O2_SDK_V1_03.tar.bz2

    # cd O2_SDK_V1_03/src/
    ===============================================================


    2.3.1 X11

      If you install Cygwin with 'All-Install' option, X11 libraries will be installed
      automatically as default.

      However, sample programs and other user programs MIGHT NOT work properly
      if you run them on the default 'Cygwin' program.

      You MUST compile and run them on the 'XWin Server' program.

      # ./configure --with-run-env=x11

      If you fail the above command, try again with '--with-x11-path' option as follows.
      # ./configure --with-run-env=x11 --with-x11-path=[X11 library path]

      # make

      Run sample1
      # cd sample1
      # ./sample1.o2.exe

      Run sample2
      # cd sample2
      # ./sample2.o2.exe

      Run stopwatch
      # cd stopwatch
      # ./STOPWATCH_V1.o2.exe


    2.3.2 O2PMP

      # make clean
      # ./configure --host=arm-linux
      # make

      In order to run sample programs on O2PMP, connect O2PMP to your PC via USB cable.

      And copy the generated file, 'sample1.o2', 'sample2.o2', or 'STOPWATCH_V1.o2',
      to the directory, 'USRPROG', in the O2PMP device with a related folder
      that are needed for execution such as 'sample1/', 'sample2/' or 'stopwatch/' folder.

      Reboot and click 'usrprog' icon in UTILITIES menu and run the .o2 file.


3. HOW-TO Start New Project

  3.1 Create Project Directory

    Move to 'O2_SDK_V1_03/src/' directory.

    Create a folder for new project. (e.g. hello_world)
    # mkdir hello_world


  3.2 Create a source file for new project

    Move to the project directory you just made.
    # cd hello_world

    Create a source file as below. (e.g. hello_world.c)

    ===============================================================
    // hello_world.c
    #include <stdio.h>

    int main(void)
    {
      printf("hello world\n");
      return 0;
    }
    ===============================================================


  3.3 Create 'Makefile.am' in your new project directory

    Create 'Makefile.am', and write as follows.

    ===============================================================
    INCLUDES =  -I./ \
                -I$(top_srcdir)/$(CWN_LIB_PATH)/

    bin_PROGRAMS = hello_world.o2

    INC_AR = $(top_builddir)/$(CWN_LIB_PATH)/libcwn.a

    hello_world_o2_LDADD = $(LIBOBJS) \
                           $(INC_AR) \
                           $(DEP_LIBS)

    hello_world_o2_SOURCES = hello_world.c

    if ENABLE_STATIC_OUT
    hello_world_o2_LDFLAGS = -static -s
    else
    hello_world_o2_LDFLAGS = -s
    endif

    clean:
        rm -rf *.o $(bin_PROGRAMS)
    ===============================================================

    Directory structure will be as below.

    O2_SDK_V1_03 +-- src +-- cowon_lib
                 |       |
                 |       +-- cowon_x11_lib
                 |       |
                 |       +-- sample1
                 |       |
                 |       +-- sample2
                 |       |
                 |       +-- stopwatch
                 |       |
                 |       +-- hello_world +-- hello_world.c    <-----+
                 |                       |                          |
                 |                ^      +-- Makefile.am      <-----+
                 |                |                                 |
                 |                +-----------------+---------------+
                 |                                  |
                 |                    Newly created folder and files
                 |
                 |
                 +-- toolchain +-- cygwin_toolchain
                               |
                               +-- linux_toolchain


  3.4 Modifying 'configure.ac' in 'O2_SDK_V1_03/src/' directory

    Open the file, 'configure.ac', and find the following lines.

    ===============================================================
    AC_CONFIG_FILES([
      Makefile
      cowon_lib/Makefile
      cowon_x11_lib/Makefile
      sample1/Makefile
      sample2/Makefile
      stopwatch/Makefile
    ])
    ===============================================================

    Add the below line as follows.
    hello_world/Makefile

    ===============================================================
    AC_CONFIG_FILES([
      Makefile
      cowon_lib/Makefile
      cowon_x11_lib/Makefile
      sample1/Makefile
      sample2/Makefile
      stopwatch/Makefile
      hello_world/Makefile        <-- ADD Here
    ])
    ===============================================================


  3.5 Modify 'Makefile.am' in 'O2_SDK_V1_03/src/' directory

    When you open 'Makefile.am' file you will see as below line.

    ===============================================================
    SUBDIRS = $(CWN_LIB_PATH) sample1 sample2 stopwatch
    ===============================================================

    Change the folder name you made as follows.

    ===============================================================
    SUBDIRS = $(CWN_LIB_PATH) sample1 sample2 stopwatch hello_world
    ===============================================================


  3.6 Re-create file 'configure'

    Use the following command to re-create the file, 'configure'.
    # rm -f configure
    # sh autogen.sh


  3.7 Configure

    # ./configure --with-run-env=x11

    or

    # ./configure --with-run-env=x11 --with-x11-path=[X11 libraries path]


  3.8 Build and Compile

    # make


  3.9 Run an example program on Linux or Cygwin

    # cd hello_world
    # ./hello_world.o2      <- on Linux

    or

    # ./hello_world.o2.exe    <- on Cygwin


  3.10 Run an example program on O2PMP

    You MUST do 'configure' and 'make' to run programs on O2 PMP as below.

    # make clean
    # ./configure --host=arm-linux
    # make

    After that, connect O2PMP to your PC via USB cable.
    And copy the generated file, 'hello_world.o2', to the directory, 'USRPROG',
    in the O2PMP device and reboot the device.

    Click 'usrprog' icon in UTILITIES menu and run the .o2 file.


  If you want to modify your source files, you don't have to do the above all Processes.

  Just move to the directory you made, and use the 'make' command.

  # make


Appendix A.

  A.1 What is X11?

    The X Window System (commonly X11 or X) is a window system that
    implements the X display protocol and provides windowing on bitmap displays.

    It provides the standard toolkit and protocol with which to build GUIs
    on most Unix-like operating systems.

    ref.) http://en.wikipedia.org/wiki/X_Window_System


  A.2 What is Cygwin?

    Cygwin is an emulator supporting Linux-like environment for Windows.

    It is a collection of tools to provide in Windows a command line and
    programming interface familiar to Unix(or Linux).

    If you want more information, visit the website, http://cygwin.com/.


Appendix B.

  B.1 HOW-TO Install gcc libraries in Linux (Ubuntu)

    # sudo apt-get install build-essential


  B.2 HOW-TO Install X11 libraries on Linux (Ubuntu)

    # sudo apt-get install libx11-dev


  B.3 HOW-TO Install autoconf in Linux (Ubuntu)

    # sudo apt-get install autoconf


  B.4 HOW-TO Install automake in Linux (Ubuntu)

    # sudo apt-get install automake