0.6 pre-release (#137)

* Manual completed (first draft)
* Remove LFS from workflows and repo
* macOS codesign and notarization

.gitattributes

@@ -1,2 +0,0 @@
-*.icns filter=lfs diff=lfs merge=lfs -text
-*.ico filter=lfs diff=lfs merge=lfs -text

.github/workflows/build-macos.yml

@@ -24,13 +24,35 @@ jobs:
     runs-on: macos-11
 
     steps:
-    - uses: actions/checkout@v3
+    - name: Checkout Repository
+      uses: actions/checkout@v3
+
+    - name: Setup Certification Keychain
+      # Codesign and submit the binary for notarization before packaging for release
+      # Reference: https://docs.github.com/en/actions/deployment/deploying-xcode-applications/installing-an-apple-certificate-on-macos-runners-for-xcode-development
+      env:
+        BUILD_CERTIFICATE_BASE64: ${{secrets.APPLE_BUILD_CERTIFICATE_BASE64}}
+        CERT_PASSWORD: ${{secrets.APPLE_BUILD_CERT_P12_PASSWORD}}
+        KEYCHAIN_PASSWORD: ${{secrets.APPLE_LOCAL_KEYCHAIN_PASSWORD}}
+      run: |
+        CERTIFICATE_PATH=$RUNNER_TEMP/build_certificate.p12
+        KEYCHAIN_PATH=$RUNNER_TEMP/app-signing.keychain-db
+        # import certificate and provisioning profile from secrets
+        echo -n "$BUILD_CERTIFICATE_BASE64" | base64 --decode -o $CERTIFICATE_PATH
+        # create temporary keychain
+        security create-keychain -p "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH
+        security set-keychain-settings -lut 21600 $KEYCHAIN_PATH
+        security unlock-keychain -p "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH
+        # import certificate to keychain
+        security import $CERTIFICATE_PATH -P "$CERT_PASSWORD" -A -t cert -f pkcs12 -k $KEYCHAIN_PATH
+        security set-key-partition-list -S apple-tool:,apple:,codesign: -s -k "$KEYCHAIN_PASSWORD" $KEYCHAIN_PATH
+        security list-keychain -d user -s $KEYCHAIN_PATH
 
     - name: Configure CMake
       # Configure CMake in a 'build' subdirectory. `CMAKE_BUILD_TYPE` is only required if you are using a single-configuration generator such as make.
       # See https://cmake.org/cmake/help/latest/variable/CMAKE_BUILD_TYPE.html?highlight=cmake_build_type
       run: cmake -B ${{github.workspace}}/build -DCMAKE_BUILD_TYPE=${{env.BUILD_TYPE}} -DCMAKE_OSX_DEPLOYMENT_TARGET=10.15 -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64"
-
+          
     - name: Build
       # Build your program with the given configuration
       run: cmake --build ${{github.workspace}}/build --config ${{env.BUILD_TYPE}}
@@ -39,12 +61,31 @@ jobs:
     #  working-directory: ${{github.workspace}}/build
     #  run: ctest -C ${{env.BUILD_TYPE}}
 
-    - name: Package
+    - name: Codesign Application
+      env:
+        IDENTITY_ID: ${{secrets.APPLE_KEYCHAIN_IDENTITY_ID}}
+      run: |
+        cd ${{github.workspace}}/build
+        xattr -c ./host/Clemens\ IIGS.app
+        codesign --force --verify --verbose --timestamp --sign "$IDENTITY_ID" --options runtime ./host/Clemens\ IIGS.app
+        codesign -dv -r- ./host/Clemens\ IIGS.app
+        codesign -vv ./host/Clemens\ IIGS.app
+
+    - name: Create Package
       if: ${{ github.ref_type == 'tag'}}
       run: |
         cd ${{github.workspace}}/build
         cpack --config CPackConfig.cmake
 
+    - name: Notarize Package
+      if: ${{ github.ref_type == 'tag'}}
+      run: |
+        cd ${{github.workspace}}/build
+        PACKAGE_FILE=$(find ./out/*.dmg -print -quit)
+        echo "Notarizing $PACKAGE_FILE ..."
+        xcrun notarytool submit --apple-id ${{secrets.APPLE_DEVELOPER_ID}} --password "${{secrets.APPLE_CLEMENS_APP_PASSWORD}}" --team-id ${{secrets.APPLE_DEVELOPER_TEAM_ID}} --wait $PACKAGE_FILE
+        xcrun stapler staple $PACKAGE_FILE
+
     - name: Archive production artifacts
       if: ${{ github.ref_type == 'tag'}}
       uses: actions/upload-artifact@v3

.github/workflows/build-windows.yml

@@ -24,8 +24,6 @@ jobs:
 
     steps:
     - uses: actions/checkout@v3
-      with:
-        lfs: true
 
     - name: Add msbuild to PATH
       uses: microsoft/[email protected]

MANUAL.md

@@ -142,7 +142,18 @@ apply to most Apple II titles from the 1980s.
 
 ## Operation (Hotkeys, etc.) <a name="hotkeys"></a>
 
+![Play Screen](docs/play-screen.png)
+
 This writeup isn't meant to be a complete tutorial on operating the Apple IIgs.
+Typical usage involves finding the disk images to run, loading them into the
+emulator and powering on the machine.
+
+Once you're able to power on a working machine, users will often run into
+situations where it's necessary to understand how the hardware works on a surface 
+level will.
+
+### Keyboard
+
 But you'll need to understand how to use the emulated Apple Desktop Bus Keyboard
 (ADB) and how keys like `Open-Apple` and `Option` map to keys on your device.
 
@@ -204,6 +215,33 @@ Clemens also supports a method to mock function keys by pressing *both* `Tux` an
 a number key to generate a function key.  For example, a user can press `Control + Right Alt + Tux + 1`
 which sends a `Control`, `Command` and `F1` key combination to the emulator. 
 
+### Joystick
+
+Apple II joysticks in Clemens are emulated as a two axis joystick with two buttons.
+
+It's usually as simple as inserting a Gamepad or modern joystick into your USB or
+connect via Bluetooth.  For notes on platform per host OS, see the below list.
+
+Clemens supports gamepad devices on the following platforms:
+
+* Windows with XInput
+  * Xbox and other gamepad devices
+  * Other devices with modern driver updates
+  * Older devices may not work (DirectInput is experimental and requires a rebuilding the app currently)
+* macOS with GameController
+  * Most modern gamepad devices
+* Linux with evdev
+  * Typically most modern gamepad devices are supported
+  * Older devices may be supported and require user configuration
+
+#### Joystick Configuraiton
+
+Select the **Machine** menu and choose **Configure Joystick**.  Options are provided to
+modify the center point of the emulated joystick, and the ability to map gamepad buttons
+to Button 0 and 1.
+
+![Joystick Config](docs/joystick-config.png)
+
 ## Finding ROM and Software Files <a name="finding-roms"></a>
 
 Clemens doesn't distribute any IIgs ROMs or software since they are still copyrighted
@@ -219,6 +257,29 @@ contains WOZ disk images useful for copy protected software.
 
 ## Debugger <a name="debugger"></a>
 
+To enter the debugger screen, select the **View** menu and choose **Debugger Mode**.
+Alternately one can press the **Bug** button in the lower left hand side of the
+main view.
+
+![Debug View](docs/debug-screen.png)
+
+The Debug View is a work in progress but does currently have some useful features,
+some of which include:
+
+* Inspect and modify register and processor status.
+* Inspect and modify Memory
+* View debugging logs
+* Component views such as IWM and Ensoniq/DOC microcontrollers
+* Set read/write/execute breakpoints and step over instructions
+* Dump memory contents to file
+* Write instruction traces to file
+* Load and save binary data to memory
+
+In the lower right side of the screen is a console.  By clicking inside the
+edit box, one can enter commands.
+
+Type 'h' to display a list of commands in the console. 
+
 ## Troubleshooting <a name="troubleshooting"></a>
 
 ## Missing Features <a name="known-issues"></a>

host/CMakeLists.txt

@@ -126,7 +126,6 @@ elseif (CMAKE_SYSTEM_NAME STREQUAL "Linux")
         "${CMAKE_CURRENT_SOURCE_DIR}/clem_host.cpp")
 elseif (CMAKE_SYSTEM_NAME STREQUAL "Darwin")
     set(clemens_ICON_FILE "${CMAKE_CURRENT_SOURCE_DIR}/resources/icon.icns")
-    set_source_files_properties(${clemens_ICON_FILE} PROPERTIES MACOSX_PACKAGE_LOCATION "Resources")
     set(PLATFORM_SOURCES
         "${CMAKE_CURRENT_SOURCE_DIR}/platform/host_macos.m"
         "${CMAKE_CURRENT_SOURCE_DIR}/clem_host.mm")
@@ -191,11 +190,13 @@ elseif(APPLE)
         OUTPUT_NAME "Clemens IIGS"
         MACOSX_BUNDLE TRUE
         MACOSX_BUNDLE_BUNDLE_NAME "Clemens IIGS"
+        MACOSX_BUNDLE_GUI_IDENTIFIER "com.cinekine.clemens"
         MACOSX_BUNDLE_BUNDLE_VERSION "${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}.${PROJECT_VERSION_PATCH}"
         MACOSX_BUNDLE_SHORT_VERSION_STRING "${CLEM_HOST_VERSION_MAJOR}.${CLEM_HOST_VERSION_MINOR}.${CLEM_HOST_VERSION_PATCH}"
         MACOSX_BUNDLE_COPYRIGHT "Copyright ${CLEM_HOST_COPYRIGHT_YEAR} Samir Sinha DBA Cinekine"
         MACOSX_BUNDLE_INFO_PLIST "${CMAKE_CURRENT_SOURCE_DIR}/macos_bundle_info_plist.in"
         MACOSX_BUNDLE_ICON_FILE icon.icns
+        RESOURCE "${clemens_ICON_FILE}"
         XCODE_ATTRIBUTE_EXECUTABLE_NAME "Clemens IIGS")
 
 endif()

host/clem_configuration.cpp

@@ -265,20 +265,23 @@ int ClemensConfiguration::handler(void *user, const char *section, const char *n
                 fmt::print(stderr, "Invalid Joystick binding index {}\n", joyIndex);
                 return 0;
             }
-            const char *valueSep = value + strnlen(value, 256);
-            unsigned btnId;
-            if (std::from_chars(value, valueSep, btnId, 10).ec != std::errc{}) {
-                fmt::print(stderr, "Invalid Joystick Button Id {}={}\n", name, btnId);
-                return 0;
-            }
-            config->joystickBindings[joyIndex].button[0] = btnId;
-            valueSep++;
-            const char *valueEnd = valueSep + strlen(valueSep);
-            if (std::from_chars(valueSep, valueEnd, btnId, 10).ec != std::errc{}) {
-                fmt::print(stderr, "Invalid Joystick Button Id {}={}\n", name, btnId);
+
+            int valueInt;
+            if (std::from_chars(value, value + strnlen(value, 4), valueInt, 10).ec != std::errc{}) {
+                fmt::print(stderr, "Invalid Joystick binding index not found {}={}\n", name, value);
                 return 0;
+            } 
+
+            partial += 2;
+            if (strncmp(partial, "adjX", 4) == 0) {
+                config->joystickBindings[joyIndex].axisAdj[0] = valueInt;         
+            } else if (strncmp(partial, "adjY", 4) == 0) {
+                config->joystickBindings[joyIndex].axisAdj[1] = valueInt;         
+            } else if (strncmp(partial, "btn0", 4) == 0) {
+                config->joystickBindings[joyIndex].button[0] = valueInt;         
+            } else if (strncmp(partial, "btn1", 4) == 0) {
+                config->joystickBindings[joyIndex].button[1] = valueInt;         
             }
-            config->joystickBindings[joyIndex].button[1] = btnId;
         }
     }
 

host/clem_front.cpp

@@ -3237,8 +3237,12 @@ void ClemensFrontend::doJoystickConfig(ImVec2 anchor, ImVec2 dimensions) {
                                    ImGuiWindowFlags_Modal | ImGuiWindowFlags_NoScrollbar |
                                        ImGuiWindowFlags_NoTitleBar)) {
             auto &bindings = config_.joystickBindings[joystickIndex];
-            ImGui::Text(CLEM_L10N_LABEL(kLabelJoystickButtonBinding), joystickIndex);
-
+            auto contentAvail = ImGui::GetContentRegionAvail();
+            auto textSize = ImGui::CalcTextSize(CLEM_L10N_LABEL(kLabelJoystickButtonBinding));
+            ImGui::SetCursorPos(ImVec2((contentAvail.x - textSize.x) * 0.5f, (contentAvail.y - textSize.y) * 0.5f));
+            ImGui::PushTextWrapPos();
+            ImGui::Text(CLEM_L10N_LABEL(kLabelJoystickButtonBinding), joystickButtonIndex);
+            ImGui::PopTextWrapPos();
             if (joysticks_[joystickIndex].buttons & CLEM_HOST_JOYSTICK_BUTTON_A) {
                 for (unsigned buttonBindingIndex = 0; buttonBindingIndex < 2;
                      ++buttonBindingIndex) {

host/strings/clem_help.inl

@@ -17,15 +17,14 @@ First time users will be prompted to set a location where the emulator will stor
 * Joystick
 * Save/Load snapshots
 * Most disk image formats (.2mg, .woz, .po, .do, .dsk)
-* Smartport Hard Drives (32MB only on Slot 2, Drive 1)
 
 ## Missing Features
 
 * ROM 1 support
 * Host desktop mouse integration
 * Serial (SCC) communications
-* PAL display
 * Monochrome display
+* Uthernet
 )md"};
 
 const char *kDiskSelectionHelp[] = {R"md(