Commit 2247f56f authored by Callum Prentice's avatar Callum Prentice
Browse files

Update the main README file to reflect the multiple changes I made, will make...

Update the main README file to reflect the multiple changes I made, will make and might make. There is also a note about the merging of the Linden autobuild files into the canonical Dullahan repository
parent c83b6781
......@@ -4,20 +4,14 @@
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 features like JavaScript or cookies.
#### **Important note**:
This is a __very__ early release - more than alpha quality but less than beta. I have high hopes this will develop into something useful but there is still a lot of work to do first.
#### **Documentation needs updating**:
The parts of this document that relate to building CEF are outdated as of 2019-09-11 and need to be updated. Once I have all the scripts working again on both Windows and macOS, I will update this document accordingly.
## What could I use it for?
It might be useful in a number of situations - for example:
* Anywhere you want to render web content in a graphics application - e.g. help pages in an OpenGL based game
* VR based video chat and shared environments (I'm working on an app like this now)
* VR based video chat and shared environments
* HTML/JavaScript based user interfaces E.G. a tablet based paradigm for VR
* Integration with JavaScript for automated site testing like [PhantomJS](http://phantomjs.org/)
* Integration with JavaScript for automated site testing
* Web page contents analysis - E.G:
* Capture images the most popular 500 web pages and count the top 5 colors in each.
* Capture a Google Maps traffic map of where you live for 24 hours and see how *really* miserable your commute is :)
......@@ -32,77 +26,51 @@ From the [CEF Wiki](https://en.wikipedia.org/wiki/Chromium_Embedded_Framework) p
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 dauting task and needs a toolset I do not have on my computer (E.G. Visual Studio 2015) so I used the builds that Spotify kindly hosts [here](http://opensource.spotify.com/cefbuilds/index.html).
## Which version of CEF does Dullahan use?
Dullahan currently builds against the [Spotify Opensource CEF site](http://opensource.spotify.com/cefbuilds/index.html) build of CEF but with some small tweaks to take account of CEF interface changes etc. it should work with slightly older or more recent versions too. For the exact version in use, you can inspect one of the [build batch files](https://bitbucket.org/lindenlab/dullahan/src/default/tools/build_win.bat?at=default&fileviewer=file-view-default#build_win.bat-10). files.
## 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 the code became very disjointed and messy. This effort is an attempt to unburden the API from those requirements and provide a more generic version which can be useful in other applications.
## Which platforms are supported?
* Windows 32/64 bit (primary development platform)
* macOS 64 bit (works, is supported but needs a little work - any macOS devs out there want to help?)
* Linux 64 bit (not available yet but hopefully one day - any Linux devs want to help?)
## Which version of the C++ runtime library does it use on Windows?
For historical reasons, both Dullahan and the version of CEF it consumes are built with the C++ runtime library set to `Multi-threaded DLL` / `Multi-threaded Debug DLL`.
## Is there a binary version I can download? ##
## How do I build CEF?
Not right now. I used to store a pre-built version on the Windows 64 bit version in my DropBox but that became untenable. Once I figure out a sensible place to store a large binary package, I'll bundle up the latest SDK and examples for all the platforms.
In order to build Dullahan, you need to build CEF. You can acquire or build a compatible version of CEF in a number of ways:
## What are the system requirements to build CEF and Dullahan?
* Use the CEF package from the Spotify Automated CEF Builds page
* Look at `build_dullahan_mac.sh` and `build_dullahan_mac.bat`in the `tools` directory
* Use a Linden Lab autobuild package for CEF
* Look at the `extract_3p_cef_wrapper_mac.sh` and `extract_3p_cef_wrapper_mac.bat` in the `tools` directory
* Build CEF from source entirely. This also means building Chromium from source too which takes a long time and needs to be done on a higher end spec computer
* Look at the `build_cef_src_mac.sh` and `build_cef_src_win.bat` in the `tools` directory
* You will have to do this if you want to enable the `media_codec` option in builds that enables support for sites like Twitch, YouTube Live and Zoom
* Windows
* Microsoft Visual Studio 2013 update 4
* [CMake](https://cmake.org/) version 3.6.3 or later
* [7-Zip](www.7-zip.org/) 7-Zip or a similar tool that can uncompress `.tar.bz2` files
* macOS
* [Xcode](https://developer.apple.com/xcode/) version 10 or later
* [CMake](https://cmake.org/) version 3.6.3 or later
* Lots more information about building CEF on all platforms can be found on the `cef / MasterBuildQuickStart` page [here](https://bitbucket.org/chromiumembedded/cef/wiki/MasterBuildQuickStart#markdown-header-mac-os-x-setup)
## How do I build CEF?
## How do I build Dullahan?
Before you can build Dullahan, you will need to build a version of CEF. There are some scripts to help - a [batch](https://bitbucket.org/lindenlab/dullahan/src/default/tools/make_dullahan_cef_pkg.bat?) file for Windows and a [shell script](https://bitbucket.org/lindenlab/dullahan/src/default/tools/make_dullahan_cef_pkg.sh) for macOS. The macOS version is somewhat automated but the lack of built-in tools in Windows to download and uncompress `.tar.bz2` files means it needs some manual steps up front.
Once you have a build of CEF in hand using one of the steps above, you can proceed with a build of Dullahan:
* Windows
* Grab a Windows 32 or 64 bit build of CEF from [http://opensource.spotify.com/cefbuilds/index.html](http://opensource.spotify.com/cefbuilds/index.html)
* Extract the archive to a local folder - I use the Windows Desktop
* Edit the `tools/make_dullahan_cef_pkg.bat` batch file - specifically, the lines at the top of the file that set the `CEF_VERSION` (match the version you downloaded), `SRC_DIR_32/64` (location of uncompressed CEF package you just downloaded) and `DST_DIR_32/64` (location where you want to generate a build).
* From a command prompt, run `tools\make_dullahan_cef_pkg.bat` with a parameter of either 32 or 64 to set the bit-width to build
* If all goes well, you will end up with a set of libs, headers and binary files in the `DST_DIR_32/64` folder that you can use to build Dullahan
* macOS
* Edit the `tools/make_dullahan_cef_pkg.sh` shell script and make sure the `CEF_VERSION` variable is set to the version you want and make sure the `DST_DIR` points to somewhere sensible. This is where the build will be generated.
* From a terminal prompt, run `tools/make_dullahan_cef_pkg.sh`. This will download the right version of CEF, build it and create a set of libs, frameworks, headers etc. that you need to build Dullahan
* Use `build_dullahan_mac.sh` and `build_dullahan_mac.bat` to build Dullahan and the examples
* Pass in the location of the CEF build you made earlier as the first parameter
* For example: `tools/build_dullahan_mac.sh ./cef_builds/cef80.1.0.6`
## Do I need to build Chromium?
## What are the system requirements for building CEF and Dullahan?
The easy answer is no - CEF builds against [Chromium](https://www.chromium.org/) but the [Spotify](http://opensource.spotify.com/cefbuilds/index.html) builds already do that for you. However, you can build Chromium yourself and then build CEF against that in the same way as Spotify does - you might need to do this if you had to change the way part of Chromium works or more likely, you wanted a version of Chromium that has the proprietary media codec support turned on. The Dullahan project used to do this but the toolset required to build Chromium passed what I had available to me (Visual Studio 2015 is a dependency for recent builds) so we stopped doing it. The remnants of a batch file can be found in [here](https://bitbucket.org/lindenlab/dullahan/src/default/tools/cef_download_build.bat) - some pieces of that may still be useful. There is also a CEF [wiki page](https://bitbucket.org/chromiumembedded/cef/wiki/BranchesAndBuilding.md) that has lots of details too.
* The requirements for building Chromium and CEF change frequently
* The requirements for building Dullahan mirror those of CEF and Chromium
* The most up to date version will always be on the `cef / BranchesAndBuilding` page [here](https://bitbucket.org/chromiumembedded/cef/wiki/BranchesAndBuilding.md#markdown-header-background).
## How do I build Dullahan?
## What are those odd files in the root directory
* Download or clone the Dullahan source code
* Windows
* Edit the `tools\build_win.bat` filer and change the `CEF_VERSION` variable to match the one you want to use and the `CEF_32_DIR` and `CEF_64_DIR` variables at the top to point to the appropriate build of CEF you just built.
* From a command prompt, run `tools/build_win.bat` with a parameter of either 32 or 64 to set the bit-width to build
* If Dullahan builds correctly, Visual Studio 2013 solution file in `build` or `build64` will open and you can run the examples like `WebCube` in the normal way
You might notice some rather unusual files in the root directory of the Dullahan repository - for example: `build-cmd.sh`, `BuildParams`, `version.cpp` They are used to build the Linden Lab [autobuild](http://wiki.secondlife.com/wiki/Autobuild) version of the Dullahan package that is then used in our product which is called [Second Life](https://secondlife.com). The [autobuild](http://wiki.secondlife.com/wiki/Autobuild) system is what we use to build all of our internal software and requires that those files be there in the root directory. You can safely ingore them if you are using Dullahan for something outside Second Life.
* macOS
* Edit the `tools/build_mac.sh` file and edit the `CEF_VERSION` variable to match the one you want to use and the `CEF_BUILDS_DIR` variable to point to the version of CEF you just built.
* From a terminal prompt, run `tools/build_mac.sh`.
* If it builds correctly, you can try to the run the included macOS example application (`open build64/Release/osxgl.app`)
* You can open the Xcode project file `build64/dullahan.xcodeproj` and edit files if you want to experiment
## Which version of the C++ runtime library does it use on Windows?
## Which files do I need in my own project?
For historical reasons, both Dullahan and the version of CEF it consumes are built with the C++ runtime library set to `Multi-threaded DLL` / `Multi-threaded Debug DLL`
The reason to use Dullahan vs raw CEF in your application is that you merely include the `dullahan.h` header file in your application and link against the `Dullahan`, `libcef` and `libcef_dll_wrapper` static libraries. Then, copy over the various CEF/Chromium runtime files alongside your application - see the post-build step for the examples in Visual Studio or the `build_mac.sh` script for more details.
## Is there a binary version I can download? ##
TODO: Create a batch file and shell script that generates a CMake file which creates an empty project with everything set up correctly.
Not right now. I used to store a pre-built version on the Windows 64 bit version in my DropBox but that became untenable. Once I figure out a sensible place to store a large binary package, I'll bundle up the latest SDK and examples for all the platforms.
## How do I use it?
......@@ -110,21 +78,12 @@ The short answer is look at the code in the `examples` folder and `dullahan.h`.
## Are there examples?
Why yes there is - take a look in the `examples` subdirectory of this repo. There are some screenshots and short descriptions in the [README](https://bitbucket.org/lindenlab/dullahan/src/default/examples/README.md) file too
## What is left to do before the first real release?
* Implement proper Dullahan <--> JavaScript interoperability
* Improve the documentation
* Make sure all the features are used in the examples to help understand usage
* Unit tests
* Add support for different pages on each side of the Web Cube example
* Lots and lots more... please help if you can.
Why yes there is - take a look in the `examples` subdirectory of this repository. There are some screen shots and short descriptions in the [README](https://bitbucket.org/lindenlab/dullahan/src/default/examples/README.md) file too
## Alternatives
* The most exciting alternative in this space is from Google themselves - [headless Chromium](https://chromium.googlesource.com/chromium/src/+/lkgr/headless/README.md) appears to offer much of what Dullahan does albeit better because they have more than one person working on it :) It's very new and still developing but definitely worth a look and will likely supersede Dullahan one day.
* The most exciting alternative in this space is from Google themselves - [headless Chromium](https://chromium.googlesource.com/chromium/src/+/lkgr/headless/README.md) and [Puppeteer](https://developers.google.com/web/tools/puppeteer) both appear to offer much of what Dullahan does albeit better because they have more than one person working on it :) It's very new and still developing but definitely worth a look and will likely supersede Dullahan one day.
## Why the name?
[Seemed appropriate](https://www.google.com/search?q=dullahan)
[Seemed appropriate](https://en.wikipedia.org/wiki/Dullahan)
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