====== xdhcefq: xdhtml renderer using Chromium Embedded Framework  ======

===== Introduction =====
//xdhcefq// is a tool, from the //Epeios// project, which handles native application with a [[..:..:xdhtml:]] interface. It uses the //[[http://bitbucket.org/chromiumembedded/cef/|Chromium Embedded Framework]] (//CEF//)// as HTML renderer.

//xdhcefq// can be build as command-line binary for //GNU/Linux//, //OS X// and //Windows//, running on //IA-32// and //AMD64// compatible processors. It's not as versatile as other Epeios-based tools (no //ARM// support, for example) as it heavily relies on //CEF//.

===== Compilation =====

See the [[computing:epeios:compilation:|compilation dedicated page]] to see how to obtain the binaries.

For //Windows//, prebuilt //Win32// binaries are available in the download section.

<note warning>Under //Windows//, due to the use of //CEF//, this tools can only be build with //Visual C++//. See the //CEF// web pages for more details.</note>

In order to compile this tool, you have to [[http://www.magpcss.net/cef_downloads/|download]] //CEF// for you OS, then you have to set the //CEF// environment variable to the root directory of the unpacked package. Then follow instructions given in above indicated page.

For //GNU/Linux// and //Windows//, the //Minimal Distribution// will be enough, but for //MacOS//, you need the //Standard Distribution//.
 
<note tip> Unlike other //Epeios// tools, the standard compilation procedure (as described in above given page) doesn't work for //Windows//, but, as already mentioned, //Win32// prebuilt binary are available. There is actually no detailed procedure to compile this tool for //Windows//, as the compilation relies on //MSVC//, but creating a //MSVC// project which compiles all the provided ''.cpp'' files, with include and/or source directories definitions pointing to the ''src'' directory, and to the //CEF// package root directory, should be simple.
</note>

The //Epeios// source code generally compiles without a single warning from compiler, but, when compiling this tool, there could be some warnings, due to the //CEF// headers.

===== Installation =====

==== For GNU/Linux and Windows ====

<note>For //Window//, the binary package comes with the //CEF// framework, so you should be able to launch the frontend by only following the launching instructions at the end of this section.</note>

Create a directory, where you put the //xdhcefq// binary, and the ''xdhcefq.xcfg'' and ''xdhcefq.xlcl'' files. From the //CEF// package, put also:
  * in the same directory: 
    * the //CEF// library (''(Release|Debug)/libcef'', ''.so'' or ''.dll'', depending on your OS),
    * (for //Windows// only) the ''(Release|Debug)/widevinecdmadapter.dll'' library,
    * the ''(Release|Debug)/*.bin'' files,
    * the ''Resources/icudtl.dat'' file,
  *  at the path defined for ''Parameters/CEF/ResourcesDirPath'' in the configuration file, or in the same directory if this entry is not defined, all the ''Resources/*.pak'' files,
  * at the path defined for ''Parameters/CEF/LocaleDirPath'' in the configuration file the files in ''Resources/locales'', or in the same directory if this entry is not defined the ''Resources/locales'' directory.

Put also in this directory the ''CEF'' directory from the //xdhcefq// package. Modify the ''URL'' entry of the ''xdhcefq.xcfg'' file to point to the ''xdhcefq.html'' in this ''CEF'' directory.

To launch the application:

''xdhcefq -m=<path to>/<module>''

where ''<module>'' is the the name of the ''xdh'' suffixed dynamic library corresponding to the application, and ''<path to>'', the path to this library. If this library is in the same directory as the tool, then give the absolute path, or ''.''.

==== MacOS ====

I am not very familiar with //MacOS// so, until I have time, or someone be willing, to create the right procedure, here is a (ugly) procedure which should work.

=== CEF building ===

(From the ''CMakeList.mk'' provided with //CEF//.)

//Cmake// and the //XCode// developers tools must be installed.

From the root directory of the //CEF// package:

  * ''mkdir build && cd build'',
  * ''cmake -G %%"%%Xcode%%"%% -DPROJECT_ARCH=%%"%%x86_64%%"%% ..'',
  * Open and build ''cef.xccodeproj'' in the ''build'' directory under the //CEF// root directory.

=== xdhqcef installation ===

From the previously created ''build'' directory (you have probably to set your computer to developer mode to be able to do following):

   * in directory ''/tests/cefsimple/Debug/cefsimple.app/Contents/MacOS'':
    * copy the ''xdhcefq'' binary,
    * rename it to ''cefsimple'',
    * copy ''xdhcefq.xcfg'' and ''xdhcefq.xlcl'':
      *  __don't__ rename them,
      *  this ''xdhcefq.xcfg'' must have the ''Parameters/CEF/ProcessType'' set to ''Main''),
    * launch ''install_name_tool -change %%"%%@rpath/Frameworks/Chromium Embedded Framework.framework/Chromium Embedded Framework%%"%% %%"%%@executable_path/../Frameworks/Chromium Embedded Framework.framework/Chromium Embedded Framework%%"%% cefsimple''
  * in directory ''/tests/cefsimple/Debug/cefsimple.app/Contents/Frameworks/cefsimple Helper.app/Contents/MacOS'':
    * copy the ''xdhcefq'' binary,
    * rename it to ''cefsimple Helper'',
    * copy ''xdhcefq.xcfg'' and ''xdhcefq.xlcl'':
      *  __don't__ rename them,
      *  this ''xdhcefq.xcfg'' must have the ''Parameters/CEF/ProcessType'' set to ''Sub'').
    * launch ''install_name_tool -change %%"%%@rpath/Frameworks/Chromium Embedded Framework.framework/Chromium Embedded Framework%%"%% %%"%%@executable_path/../../../../Frameworks/Chromium Embedded Framework.framework/Chromium Embedded Framework%%"%% %%"%%cefsimple Helper%%"%%'',
  * Modify (or create) in __all__ ''xdhcefq.xcfg'' files the ''Parameters/ModuleFilename'' entry so it contains the path and name of the frontend dynamic library (which name is something like ''lib<name>xdh.dylib'').

To launch, double-click on ''tests/cefsimple/Debug/cefsimple.app/Contents/MacOS/cefsimple''.



===== Configuration =====

See the [[computing:epeios:configuration:|global configuration dedicated page]].

See also the [[:computing:epeios:xdhtml:#Configuration|xdhtml configuration dedicated section]]. The ''Parameters/ModulFilename'' mentioned in this section entry is set through a command-line argument (launch ''xdhcefq %%--%%help'').

There is also a ''Parameters/URL'' entry which have to point to the __absolute__ path and file name (prefixed with ''file:%%//%%'') to the provided ''xdhcefq.html'' file.

There are also some //CEF//-related parameters, grouped in the ''Parameters/CEF'' section, like ''ProcessType'', ''SingleProcess'', ''NoSandbox''... (see //CEF// documentation if you want more details about them), but their values (which varies from one OS to another) should be correctly set and not changed.

===== Bugs =====

There are some bugs in //xdhcefq// which seems due to //CEF// with following effects:
  * Some cosmetic ugliness,
  * Under //GNU/Linux//, by default, //CEF// comes with no dialog boxes implementation (//alert//, //confirm//, file related dialog boxes...). The alert and confirm dialog boxes are actually displayed using the console. For example, when you quit an application, the confirmation message appears in the console.
  * Under //GNU/LINUX//, //CTRL-SHIFT-A// does nothing (it should display the //About...// box)?

Also, if, when launching, you have a dialog box with ''Attach debugger  !'' message, simply dismiss it. It's a debugging feature which was forgotten to be deactivated.

===== Licence =====
#@H_LICENSE_HTML~xdhcefq~@#

===== Status =====
  * Last release: **20161231**,
  * #@CVS_HTML~tools/xdhcefq/CHANGELOG.txt,Changelog~@#,
  * Used CEF 3 branch : **2883**.

===== Download =====

There is no dedicated download section, as this tool is included in each package which needs it.

===== Author =====
#@H_AUTHOR_HTML~xdhcefq~@#

===== Other resources =====
  * [[computing:epeios:tools:xdhcefq:manual:|User manual]],
  * source repository:
    * [[http://hg.savannah.gnu.org/hgweb/epeios/file/tip/tools/xdhcefq/|of the tool]],
    * [[http://hg.savannah.gnu.org/hgweb/epeios/file/tip/stable|of the Epeios framework]],