Skip to content

Debugging Overlay Icons

Jump to bottom
Phil Davis edited this page Dec 13, 2016 · 12 revisions

Windows

How it works

The installer will install a COM component that holds an Explorer plugin (ShellExtensionHandler) to display overlay icons. Once installed, it will listen on a named pipe. Once a client connects, it will inquire about the state of the icon.

I don't see icons. What do I do?

  1. Check if you didn't unselect the overlay icons during installation
  2. Check if the ownCloud Desktop Client is running and is properly set up
  3. Try to restart explorer.
  4. Download ShExtView and check for entries such as OCError or OCOK.
  5. Open regedit.exe, check HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\Windows\CurrentVersion\Explorer\ShellIconOverlayIdentifiers. It should contain entries starting in OC (such as OCError, OCErrorShared, OCOK or OCOKShared all with spaces in front).
  6. Check for keys {0960F090-F328-48A3-B746-276B1E3C3722} through {0960F097-F328-48A3-B746-276B1E3C3722} in HKEY_LOCAL_MACHINE\SOFTWARE\Classes\CLSID\.

If 5. and 6. do not exist, start an elevated cmd.exe (right click, "Run as Administrator"). and type regsvr32 "C:\Program Files (x86)\ownCloud\shellext\OCOverlays_x64.dll" (on 64 bit Windows) or regsvr32 "C:\Program Files (x86)\ownCloud\shellext\OCOverlays_x86.dll"'(on 32 bit Windows).

Mac OS X (>=10.10 FinderSync version)

  1. Open shell_integration/MacOSX/OwnCloud.xcworkspace
  2. Make sure that the FinderSyncExt scheme is selected at the top (SyncStateFinder is for the <10.10 extension)
  3. Press play in XCode and select Finder as the app to run
  4. Make sure that your client is running

The default XCode build settings are to be used with a development ownCloud client

The OC_SOCKETAPI_TEAM_IDENTIFIER_PREFIX User-Defined build setting of the FinderSyncExt target should match the one set for the client through cmake. By default both are empty, allowing you to load the extension without a Deverloper ID certificate. This however means that you can't mix the official build's client and extension binaries. You have to build both yourself and if you changed it in cmake, you need to change it manually in XCode as the normal build process passes this information through xcodebuild.

If you sometimes don't see overlay icons when running the XCode project

Pressing the play button involves registering the built plugin and telling Finder to load it. This however doesn't always work well after running a few times in a row. In case of issue you can try:

  • Option-Right-Click on Finder and select Relaunch before pressing play usually helps
  • Make sure that your extension is listed and enabled in the Preferences / Extensions pane.
  • The pluginkit command line can be used to force the registration of the extension if you built it outside of XCode. XCode should however already take care of that step. The extension will run in a ownCloud Extensions secondary process, so killing that process can also help if killing Finder wasn't enough.
  • Use a different "app to run" than Finder (for example TextEdit) and test that the icons work properly through the application's Open dialog. This allows you to restart the application each time at least.
  • Watch the Console for any error if it still doesn't work. The main break issue when dealing with codesigning is usually the NSConnection::connectionWithRegisteredName call, so put some debug output or a breakpoint in the failure case if you need to investigate further.
  • On macOS Sierra activate private log to make sure you expose all <private> redacted logs: sudo log config --mode "private_data:on"

Enabling overlay icons day-to-day when developing the ownCloud client (no XCode)

You can't have both the production ownCloud running and a development version at the same time with their respective overlay icons because of the mismatching TEAM_IDENTIFIER and signature, the Finder plugin won't be allowed to connect by the sandbox. A way to have both working is to always develop using the testpilotcloud theme so that the installed FinderSync extension has a different bundle identifier.

  • Configure your client with -DOEM_THEME_DIR=<client-customer-themes>/testpilotcloud/syncclient -DCMAKE_INSTALL_PREFIX=install
  • make, the FinderSync plugin XCode project will be built with the rest
  • make install to make sure that the plug-in is copied in the client's .app bundle (pkd requires this, at least on 10.12). This is just required if you changed something in the plugin, a non-installed client can still be used with it.
  • pluginkit -a install/testpilotcloud.app/Contents/PlugIns/FinderSyncExt.appex to add the plugin to the database
  • Make sure it is enabled in System Preferences / Extensions

Mac OS X (<10.10 SyncStateFinder version)

  1. Disable the FinderSync version in Preferences/Extensions
  2. Build ownCloud on the command line as usual and start the client
  3. sudo cp -r <build_dir>/shell_integration/MacOSX/Release/SyncStateFinder.osax /Library/ScriptingAdditions/
  4. Relaunch Finder (killall Finder on the command line, or Alt-RightClick on the Finder dock icon and select Relaunch)
  5. If on OS X >= 10.10, tell Finder to load the extension manually, since the client won't trigger this automatically:
    osascript <source_dir>/shell_integration/MacOSX/load.scpt

If on OS X >= 10.11 you will need to disable the System Integrity Protection to be allowed to send script messages to Finder, or to attach a debugger to any built-in application (e.g. Finder or TextEdit)

Nautilus

tbd

☁️

Clone this wiki locally