macOS

(Cocoa) Bundles vs Lazarus Bundles

Whenever Lazarus creates an OSX bundle, it puts a symbolic link to an executable into the bundle.

prog
prog.app
  Contents
    MacOS
      prog --> ../../../prog

However CEF expects an actual executable binary instead of a symbolic link, otherwise the bundle detection fails and the library complains about missing files and resources. The debug version then outputs the following error:

 [1214/225716:FATAL:bundle_locations.mm(62)] Check failed: new_bundle. Failed to load the bundle at Contents/Frameworks/Chromium Embedded Framework.framework

Therefore the LCLSimple and SubProcess examples use an Execute after command (see fpc wiki) to copy the binary into the right place after compilation.

LCLSimple example

Instructions for the single-process mode

Please note: The single-process mode in CEF is very much unmaintained and not tested very well. It is strongly recommended to use the default multi-process mode instead.

1. open the LCLSimple project, available in the Examples directory of fpCEF3

2. switch to macOS build mode (howto)

3. modify TMainform.FormCreate method as follows:

    procedure TMainform.FormCreate(Sender: TObject);
    begin
      {$IFDEF DARWIN}
      CefSingleProcess:=true;
      {$ELSE}
      CefBrowserSubprocessPath := '.' + PathDelim + 'subprocess'{$IFDEF WINDOWS}+'.exe'{$ENDIF};
      {$ENDIF}
    end; 
   

   This will enable single process mode and an external sub process will not be needed.

4. open the simple.app bundle either by using the command line (and cd into the bundle) or using Finder (right-click and select Show Package Content)

5. copy the Chromium Embedded Framework framework into the directory Contents/Frameworks

6. compile and run the application

Instructions for the multi-process mode

For a multiprocess application additionally a subprocess application is needed. For LCLSimple the unmodified default CEF subprocess application in Examples/SubProcess can be used.

Subprocess

1. open the SubProcess project, available in the Examples directory of fpCEF3

2. switch to macOS build mode (howto)

3. compile the project

LCLSimple

1. open the LCLSimple project, available in the Examples directory of fpCEF3

2. switch to macOS build mode (howto)

3. modify TMainform.FormCreate method as follows:

   procedure TMainform.FormCreate(Sender: TObject);
   begin
     {$IFDEF DARWIN}
     CefBrowserSubprocessPath :=
       ExtractFileDir(ExtractFileDir(ExpandFileName(Paramstr(0))))
       +PathDelim+'Frameworks/subprocess.app/Contents/MacOS/subprocess';
       ;
     {$ELSE}
     CefBrowserSubprocessPath := '.' + PathDelim + 'subprocess'{$IFDEF WINDOWS}+'.exe'{$ENDIF};
     {$ENDIF}
   end; 
   

4. open the simple.app bundle either by using the command line (and cd into the bundle) or using Finder (right-click and select Show Package Content)

5. copy the Chromium Embedded Framework framework into the directory Contents/Frameworks

6. copy the subprocess.app into the same directory

7. compile and run the application

General notes

• make sure to set the target OS to Darwin and the target CPU to x86_64

• Lazarus can be used to create the application bundle, however don't forget to replace the symbolic link inside the bundle with the actual binary as described here

  For the subprocess bundle one additional steps are needed:

  1. open the file Info.plist e.g. with Xcode
  2. add the parameter Application is agent (UIElement)

• CEF expects the subprocess application bundle and executable to be named <APPNAME> Helper. For the LCLSimple example the name would be simple Helper. If this bundle is not found inside the Frameworks folder, CEF will create it automatically.

  If the subprocess does not follow this naming rule, CefBrowserSubProcess must be set to the path of the subprocess executable (like in the description above).

  However it is recommended to follow the naming convention (unlike the description above). In this case CefBrowserSubProcess is not needed.

  Don't forget to change the CFBundleExecutable key in the Info.plist file if you rename the executable.