Commit 94af7c41 authored by Callum Prentice's avatar Callum Prentice
Browse files

Update documentation to reflect changes

parent b4222aab
#
# TODOS
# deal with code generation DLL thing?
# update docs to reflect cmake
# run astyle over souce
# 64 bit version
# move cef definition to command line for cmake
################################################################################
## minimum version required - 3.6.3+ needed to set startup project
cmake_minimum_required(VERSION 3.6.3)
......
......@@ -2,7 +2,7 @@
## What is it?
A headless browser SDK that uses the [Chromium Embedded Framework](https://en.wikipedia.org/wiki/Chromium_Embedded_Framework) (CEF). It is designed to make it easier to write applications that render modern web content directly to a memory buffer, inject synthesized mouse and keyboard events and interact with web based features like JavaScript or cookies.
A headless browser SDK that uses the [Chromium Embedded Framework](https://en.wikipedia.org/wiki/Chromium_Embedded_Framework) (CEF). It is designed to make it easier to write applications that render modern web content directly to a memory buffer, inject synthesized mouse and keyboard events as well as interact with web based features like JavaScript or cookies.
#### **Important note**:
This is __very__ much an alpha release / first code drop. I have high hopes this will develop into something useful but there is still a lot of work to do first.
......@@ -17,7 +17,7 @@ It might be useful in a number of situations - for example:
* Integration with JavaScript for automated site testing like [PhantomJS](http://phantomjs.org/) - not there at all yet but that's one of the main plans for the future
* Web page contents analysis - E.G:
* Capture images the top 500 web pages and count the top 5 colors in each.
* Capture a Google Maps traffic map of your commute for 24 hours and see how bad it is :)
* Capture a Google Maps traffic map of your commute for 24 hours and see how miserable the commute is :)
* Web page capture to an image or a PDF file
* Lots more I haven't thought of yet
......@@ -27,7 +27,7 @@ There are some examples included in this repository and there is a description a
From the [CEF Wiki](https://en.wikipedia.org/wiki/Chromium_Embedded_Framework) page: The Chromium Embedded Framework (CEF) is an open source framework for embedding a web browser engine based on the Chromium core.
An essential site to visit when developing a CEF based application is the [CEF forum](http://magpcss.org/ceforum/) started and run by (I believe) the original author Marshall Greenblatt who is very generous with his time and expertise.
An essential site to visit when developing a CEF based application is the [CEF forum](http://magpcss.org/ceforum/) started and run by (I believe) the original CEF author Marshall Greenblatt who is very generous with his time and expertise.
Building CEF locally is quite a task so Adobe kindly host builds for all supported platforms [here](http://cefbuilds.com).
......@@ -37,11 +37,11 @@ Dullahan been developed against the [CEF 3.2704](https://cefbuilds.com) build of
## What are the origins of this project?
Historically, the first incarnation was [LLCEFLib](https://bitbucket.org/lindenlab/3p-llceflib) - a [Linden Lab](http://lindenlab.com) internal library to render web content content inside [Second Life](http://secondlife.com). LLCEFLib had to support the outdated 32bit macOS version as well as many Second Life specific features so things became very disjointed and messy. This effort is an attempt to unburden the API from those requirements and provide a Windows only version that is much more generic and hopefully useful in other applications.
Historically, the first incarnation was [LLCEFLib](https://bitbucket.org/lindenlab/3p-llceflib) - a [Linden Lab](http://lindenlab.com) internal library to render web content content inside [Second Life](http://secondlife.com). LLCEFLib had to support the outdated 32bit macOS version as well as many Second Life specific features so things became very disjointed and messy. This effort is an attempt to unburden the API from those requirements and provide a more generic version and hopefully useful in other applications.
## Is Windows, 32bit the only support platform?
## Is Windows 32/64bit the only supported platform?
For the moment yes. The 32bit version for macOS is no longer supported by CEF. One day, there will be a 64bit Windows version as well and ideally, at that point, the 64bit macOs version will be added too. No plans for a Linux version but if you'd like to help, please let me know.
For the moment yes. The 32bit version for macOS is no longer supported by CEF. One day, there will be a 64bit macOS version will be added too. No plans for a Linux version since I have no easy way to develop for Linux but if you'd like to help, please let me know.
## Which version of the C++ runtime library does it use?
......@@ -49,20 +49,22 @@ For historical reasons, both it and the version of CEF in this repository are bu
## How do I build Dullahan?
* Download or clone the source code here
* Build or grab the version of CEF you want to use (See below)
* Download or clone the Dullahan source code
* Build or download the version of CEF you want to use (See below)
* Ensure Microsoft Visual Studio 2013 (update 4) is installed (it might work with other versions but that is untested)
* Open `dullahan.sln`.
* Select the Release or Debug configuration and build the solution in the normal fashion.
* If all goes well, you can set one of the example applications as the startup project and try it.
## Binary distribution of example applications
If you would like to try the Dullahan example applications without having to build them, thee is a zipped binary distribution in the `bin` folder. It contains all the CEF/Chromium runtime files as well as the example executables.
* Make sure [CMake](https://cmake.org/) version 3.6.3 or later is installed on your system
* Note: a rudimentary batch file that runs these steps automatically can be found in `tools\build_win.bat` - otherwise, follow the manual steps below
* Create a new directory off of the project root `mkdir build` and switch to it `cd build`
* Use CMake to generate project files `cmake -G "Visual Studio 12 2013" -DCEF_DIR="c:\work\cef_builds\cef_2704.1434.win32" ..` where `CEF_DIR` points to the absolute path of a version of CEF that you built or downloaded
* Note: For 64 bit builds, invoke CMake like this `cmake -G "Visual Studio 12 2013 Win64" -DCEF_DIR="c:\work\cef_builds\cef_2704.1434.win64" ..`
* Either open the resulting `dullahan.sln` in Visual Studio as normal or build everything on the command line using `msbuild dullahan.sln /p:Configuration=Release`
* Switch to the output directory `cd Release` and run the example `.\webcube`
* The Dullahan header you need can be found in `src` directory
* The Dullahan library file you need can be found in `build\Release | Debug` directory
## Which files do I need in my own project?
The main benefit of using Dullahan vs raw CEF is that you simply include the `dullahan.h` header file in your application and link against the `dullahan.lib` library along with two small CEF ones. Then, copy over the various CEF/Chromium runtime files along side your application - see the post-build step for the examples in Visual Studio for a list - and you are ready to go.
The main benefit of using Dullahan vs raw CEF is that you simply include the `dullahan.h` header file in your application and link against the `dullahan.lib`, `libcef.lib` and `libcef_dll_wrapper.lib`. Then, copy over the various CEF/Chromium runtime files alongside your application - see the post-build step for the examples in Visual Studio for a list - and you are ready to go.
## How do I use it?
......@@ -70,14 +72,13 @@ The short answer is look at the code in the `examples` folder and `dullahan.h`.
## Grabbing CEF
* Make sure [CMake](https://cmake.org/) is installed on your system
* Grab a Windows 32-bit build of CEF from [http://cefbuilds.com](http://cefbuilds.com)
* Extract the 7Zip archive to a folder in an easy to find place - I use the desktop
* Edit the `tools/make_dullahan_cef_pkg.bat` batch file - specifically, the lines at the top of the file that set the CEF folder you just unpacked and the destination folder of the Dullahan compatible package.
* Make sure [CMake](https://cmake.org/) version 3.6.3 or later is installed on your system
* Grab a Windows 32 or 64 bit build of CEF from [http://cefbuilds.com](http://cefbuilds.com)
* Extract the 7Zip archive to a folder in an easy to find place - I use the desktop
* Edit the `tools/make_dullahan_cef_pkg.bat` batch file - specifically, the lines at the top of the file that set the bit width, the CEF folder you just unpacked and the destination folder of the Dullahan compatible package.
* Run the batch file
* If all goes well, you will end up with a Dullahan CEF package in the `DST_DIR` folder you set
* Move that to the `cef` folder in this project, edit the `src/dullahan.props` file and update the `CEF_DIR` variable to point to the folder
* Build Dullahan
* If all goes well, you will end up with a CEF package in the `DST_DIR` folder
* Build Dullahan as per instructions above
If this step failed then you will have to inspect the batch file. Generally speaking, this is what it does:
......@@ -86,12 +87,11 @@ If this step failed then you will have to inspect the batch file. Generally spea
* Build everything
* Copy files to the right place
Another option is to build the whole thing from scratch. This is necessary if you want to make changes to the Chromium code or perhaps turn on the proprietary media codecs support which is not available in the [CEF Builds](http://cefbuilds.com) versions. For more information on how to do this, look online or inspect the `tools/build_cef.bat` batch file.
Another option is to build the whole thing from scratch. This is necessary if you want to make changes to the Chromium code or perhaps turn on the proprietary media codec support which is not available in the [CEF Builds](http://cefbuilds.com) versions. For more information on how to do this, look online or inspect the `tools/build_cef.bat` batch file.
## What is left to do before the first real release?
* Consider using CMake to generate the Dullahan project files
* Add support for 64bit windows, macOS and Linux versions
* Add support for 64bit macOS
* Implement proper Dullahan <--> JavaScript interoperability
* Improve the documentation
* Try to find a way to grab CEF builds automagically vs that crazy build steps in the docs
......@@ -100,10 +100,6 @@ Another option is to build the whole thing from scratch. This is necessary if yo
* Add support for different pages on each side of the Web Cube example
* Lots and lots more... please help if you can.
## What is `dullahan_src_hash.hpp`
In an effort to come up with a way to uniquely identify a version, I experimented with taking an MD5 hash of all the source code and using part of that in the version number string. A Pre-Build in the Visual Studio Project file step does this and writes out `dullahan_src_hash.hpp`. The hash in this header file is then combined with the CEF version, the Chrome version it represents as well as a Dullahan version into a single string that uniquely identifies the build. I'm still not sure this is a good idea but I'll leave in there until someone explains to me how stupid it is.
## Why the name?
[Seemed appropriate](https://www.google.com/search?q=dullahan)
\ No newline at end of file
# Tools that are useful for working with CEF and Dullahan
`build_cef.bat`
`build_win.bat`
Simple batch file to build Dullahan as well as an example application. Pass in 32 or 64 for 32/64bit versions.
`cef_download_build.bat`
Batch file that grabs the latest version of automate-git.py and uses it to build CEF from source. You might want to do this if you want to enable the embedded support of media including MPEG-4 files.
......@@ -14,7 +18,7 @@ Batch file that uses a CEF build made using build_cef.bat and extracts files (DL
`make_src_hash.bat`
Batch file used to generate a hash of the cpp/h source files that is used as part of the Dullahan version number. A testbed before transplanting code into MSVC Pre-Build event.
Batch file used to generate a hash of the cpp/h source files that is used as part of the Dullahan version number. A testbed before actually using in the client
`astyle.bat`
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment