Initial commit

Torque/SDK/pb/readme.txt

@@ -0,0 +1,125 @@
+README for OSX build
+
+Contents:
+
+1) General Notes
+    1.1) Supported Versions of Mac OS
+    1.2) Recommended Development Tools
+2) Initial Setup, Tips & Goodies
+    2.1) Getting Debugging to Work
+        2.1.1) For Xcode2.1+
+        2.1.2) For ProjectBuilder, Xcode1.5, Xcode2.0
+    2.2) Script Editing in Xcode
+        2.2.1) Installing .cs Language Definitions in Xcode
+    2.3) Putting Game Content Inside the App Bundle
+3) Known issues
+
+
+1) General Notes
+---------------------------------------------------------------------------
+
+1.1) Supported Versions of Mac OS
+Recent versions of Torque on Macintosh require MacOS 10.2 or later.
+Attempting to support older versions of the MacOS is not recommended.
+
+1.2) Recommended Development Tools
+Only the Xcode 2.1 project file is currently being kept up to date.
+Previous projects aren't guaranteed to work properly, and may have issues
+not listed herein. Thus, Xcode is the recommended development environment.
+It is of course possible to use any development environment that can
+produce a Macintosh application, and can use the standard BSD & MacOSX
+headers and frameworks.
+
+
+2) Initial Setup, Tips & Goodies
+---------------------------------------------------------------------------
+
+2.1) Getting Debugging to Work
+
+  2.1.1) For Xcode2.1+
+  ----------------------------------------
+  - locate the file "fix xcode2.1 build folders.command".
+  - double-click it to launch it.
+  - the Terminal will open, and the script will run.
+  - close the Terminal window.
+  
+  The script will move aside any existing 'build' directory, and replace it
+  with a clean one containing symbolic links ( aliases ) to the 
+  "../example" directory. If you are using a different directory name than
+  "example", you can edit the script in any text editor and replace
+  "example" with your directory of choice.
+
+  2.1.2) For ProjectBuilder, Xcode1.5, Xcode2.0
+  ----------------------------------------
+  - launch the PB project.
+  - select/click the topmost group (should have same name as the project)
+  - from menu choose File->Show Info
+  - perform the following three steps in order:
+  - first: select "Place intermediate build products for this project in a
+    separate location"
+  - second: select "Place build products for this project in a separate
+    location"
+  - third: enter "../example" (without the quotes), in the upper text box.
+  - replace "example" with your folder name if you're using another name.
+  - close the window.
+  - close the project file & reopen it to force a save.
+
+  ----------------------------------------
+  Your project should now directly build the target executable directly
+  into the runtime folder, which also means it is properly located for
+  running or debugging from within Xcode / Project Builder.
+
+
+
+2.2) Script Editing in Xcode
+The Xcode project file now contains references to the script files.
+This make searching more complete, and provides a decent script editor.
+
+  2.2.1) Installing .cs Language Definitions in Xcode  
+  ----------------------------------------
+  - open the "torque/pb/script editing" folder.
+  - locate the Torque.pbfilespec and Torque.pblangspec files therein.
+  - locate the directory /Library/Application Support/Xcode/Specifications/
+  - create the Specifications directory if it does not exist.
+  - install the .pbfilespec and .pblangspec files in Specifications/ .
+  - quit and restart Xcode.
+
+
+2.3) Putting Game Content Inside the App Bundle
+The engine will assume that game content is beside the main.cs file.
+It will look first in YourGame.app/Contents/Resources, then it will 
+look in the folder where YourGame.app resides for a file named 'main.cs'.
+So, when you are ready to distribute your game, you should place the game
+content inside the application bundle like this:
+- in the Finder, control-click(or right-click) on your built application.
+- choose 'Show Package Contents'.
+- a new window will open, with one folder: 'Contents'.
+- Navigate to the Contents/Resources folder.
+- copy all your game files (main.cs, common/, etc) into Contents/Resources.
+- run the game & test all functionality.
+
+
+3) Known issues
+---------------------------------------------------------------------------
+
+- No external console window. in debug in Xcode, printfs go to the debug
+console pane. At some point, we'll likely create a simple console library
+to be used when a tertiary console window is needed. In the mean time, you
+can open the console.logfile using the Console application. Console will
+automatically 'tail' the file, always displaying the most current contents.
+  
+- ADDENDUM: printfs may also output to the system log in the Console, and
+will output to the Terminal if you manually launch the Torque app directly
+from the commandline.
+
+- OSX handles cmdline args like the PC, if you launch it from the cmdline.
+Note that this means that you can add args in the project file for debug vs release, etc.
+Take a peek at "example/Launch using show mod.command" in a text editor to see how you can use cmdline args from an external script.
+The maccmdline.txt workaround still works, if you prefer.
+
+- mac performance vs the PC has improved greatly. There is still ground to
+gain performance here, but it may not be a good investment of time. As a
+general rule, only consider optimization when you're done with everything
+else.
+
+- The mac platform code is a mess. A total rewrite is on my todo list.