brickOS README.use - easiest forms of interaction with source 

Updated: 16 Oct 2002
------------------------------------------------------------------------------

The brickOS make system is written to accommodate the following styles 
of use: 

  (s1) A person who is only interested in writing code for robots which 
       are running a pre-built brickOS. 

  (s2a) A person who wants to reconfigure the brickOS operating system 
        to enable devices or services not normally enabled in the
		default build.

  (s2b) A person who wants to experiment with the brickOS operating system 
        directly, modifying and testing it 

  (s3) A person who wants to do all of these from time to time. 


------------------------------------------------------------------------------
[s1] You want to get right to progranmming your creations and don't want to
     experiment with modifying brickOS at this time.

	 Get started by locating a pre-built environment if one exists.
	 Install it and then off you go to create programs for your creations

	 If a pre-built environment doesn't exist get the latest source 
	 .tar.gz file.  unpack it then build and install it.

	 After install, you are ready to start.  Rather than our describing 
	 how to do this let's walk thru a quick example...

To start with a prebuilt brickOS:

- Utilities, libraries, legOS kernel and demos have all been installed.
- Copy the /usr/[local/]share/doc/brickos/examples/demo/ directory contents to
  a directory of your choosing. (If you wish to use c++ copy the files 
  from the demo/c++ subdirectory, instead.)
- Type 'make' in this new directory to compile the demos.
- The utilities are already in your PATH. Set RCXTTY if you use a non-
  standard port for the IR tower.  [example: 'export RCXTTY=/dev/ttyS1']
- Use firmdl3 to download /usr/[local/]lib/brickos/brickOS.srec to your RCX.
- Type "dll demo/helloworld.lx" (where demo is the directory in which you
  just made the demos). If all is well, it should be automatically
  relocated and downloaded into program slot 0. Press the RUN key to 
  run. The program stops automatically.
- Type "dll -p1 demo/rover.lx" to transmit another demo to program slot 1.
  Use the PRGM key to select the desired program. Try RUN.
- NOTE: A 'make realclean' will remove all built files.

- Stop your program with the RUN or ON/OFF key. Programs are preserved over
  ON/OFF now.  Press ON/OFF and PRGM simultaneously to erase legOS.
  

For your own projects,

- Make a directory in a location of your choosing (you may wish to make
  a ~/brickOS directory and place your projects below there).
- Copy 'Makefile' from the /usr/[local/]share/doc/brickos/examples directory 
  to this new directory.
- Put your main routine into myproject.c. (or myproject.C if using C++)
- If you need more source files, add them in the Makefile.
- type "make myproject.lx && dll myproject.lx" to build and then download 
  your new code. (Remember to use -pN to select specific program slot)

In case you are wondering, dll is short for dynamic linker and loader.

You can get good help at: http://lugnet.com/robotics/rcx/legos/ should
you need to.

------------------------------------------------------------------------------
                     End of FILE: README.use
------------------------------------------------------------------------------
