
This directory contains the MacOS-specific code for building a Cocoa
version of xscreensaver without using X11.

############################################################################
#
#   To set up your macOS and iOS development environment:
#
############################################################################

Installation:

  - Install the latest Xcode from the App Store.  Note: it is
    mind-bogglingly gigantic.

  - Install ImageMagick ("convert"). Either MacPorts or Homebrew are
    good choices for installing open source software on macOS.


Make sure everything works:

  - Open "xscreensaver.xcodeproj" in Xcode.

  - Select "All Savers" on the "Scheme" menu in the upper left, to the
    right of the "Play / Pause" buttons.

  - ⌘B "Product / Build"

  - There will probably be a build error related to Sonar and ICMP.
    Click on the red error icon to see the error message and follow the
    instructions there to fix it.


To build and test a macOS saver:

  - Select the saver you want on the "Scheme" menu in the upper left,
    to the right of the "Play / Pause" buttons.

  - Select "My Mac" from the "platform" menu to the right of that.

  - Press "Play".  This will run the "SaverTester" app under the debugger.
    SaverTester is a testing framework that will load and run your selected
    ".saver" bundle in the same manner that "System Preferences" and
    "ScreenSaverEngine" will.

  - To get the system's screen saver to use your debug builds, you can
    do something like this:

    ln -s ~/xscreensaver/OSX/build/Debug/*.saver ~/Library/Screen\ Savers/


To build and test an iOS saver:

  - Pay Apple $100 per year for an iOS developer account.  There's no way
    to build and debug iOS code without doing this, because they are evil.

  - Select "XScreenSaver-iOS" on the "Scheme" menu.

  - On the platform menu, select your physically attached iOS device, or
    select one of the simulators.  Press "Play".

  - If you have already installed the App Store version of XScreenSaver
    on your physical iOS device, you may need to delete it before you
    can install your own debug build.


Building for older operating systems:

  Basically, you can't.  If you build using anything later than Xcode 5.0.2,
  the resultant savers will require MacOS 10.7 or later.  To support macOS
  10.4 through 10.6, you would need to be running Xcode 5.0.2 or earlier.
  Apple's longstanding corporate policy of planned obsolescence means that
  they make it as difficult as possible for you to support anything that's
  more than two years old on desktop, or six months on mobile.


############################################################################
#
#   To add a new screen saver to the Xcode project:
#
############################################################################

  It is a ridiculously long list of steps!  This list is here mostly for
  my benefit.  I tried to automate some of this with Applescript but that
  appears to be impossible.

  1: Duplicate a target (Dangerball for GL, or Attraction for X11).
  2: Rename it, and drag it to the right spot in the list.
  3: Delete the dangerball.c and dangerball.xml files from Build Phases.
  4: Delete the "DangerBall copy-Info.plist" file that got created.
  5: Delete the "DangerBall copy-Info.plist" from the Build Settings too.
  6: Manage Schemes, rename "DangerBall Copy".
  7: Move to the right place in the list.
  8. Scheme / Profile / Info: Executable: SaverTester.app.
     Scheme / Run / Info: Executable: SaverTester.app.
  9: Scheme / Run / Arguments: set SELECTED_SAVER environment variable.
 10: File / Add Files / the new .c and .xml.
 11: Re-order them in the file list. This will bring up an Options dialog.
     Add To Targets: the new target, and "XScreenSaver-iOS" and "-tvOS".
 12: The files might not have moved. This means Xcode is gonna crash soon.
     It will repair itself after.
 13: In target "All Savers (OpenGL)" add the new target as Build Phases /
     Target Dependency.
 14: In target "XScreenSaver-iOS", reorder new files in Build Phases /
     "Copy" and "Compile", since they showed up in a random place.
 15: In target "XScreenSaver-iOS", add "-DUSE_GL" to the new file's options.
 16: Put a 200x150 screen shot in ~/www/xscreensaver/screenshots/
 17: ln -s ../../src/xscreensaver/OSX/build/Debug/NEW.saver \
           ~/Library/Screen\ Savers/
 18: git add xscreensaver.xcodeproj/xcshareddata/xcschemes/*.xcscheme
 19: Don't forget to create a man page from the XML with xml2man.pl,
     and update Makefile.in.
 20: Make a video: -record-animation 3600 -geom 1920x1080+128+64
     ./upload-video.pl NAME
