Skip to content

Commit

Permalink
First cut of README, but still some work to be done
Browse files Browse the repository at this point in the history 
Signed-off-by: Diego Molina <diemol@gmail.com>
  • Loading branch information
@mmerrell-sauce @diemol
mmerrell-sauce authored and diemol committed Sep 18, 2019
1 parent b32d062 commit 38cd7bc
Showing 1 changed file with 106 additions and 135 deletions.
241 changes: 106 additions & 135 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -35,102 +35,92 @@ before submitting your pull requests.

## Building

Selenium uses a custom build system, aptly named
[crazyfun](https://github.com/SeleniumHQ/selenium/wiki/Crazy-Fun-Build)
available on all fine platforms (Linux, Mac, Windows). We are in the
process of replacing crazyfun with
[buck](https://buckbuild.com/), so don't be alarmed if you
see directories carrying multiple build directive files.
For reference, crazyfun's build files are named *build.desc*,
while buck's are named simply *BUCK*.

Before building, ensure that you have Chrome browser installed and the
In order to build Selenium, you'll generally use the `./go` command. `./go` is a Rake script,
which wraps the main build too, `bazel`.

### Bazel

[Bazel](https://bazel.build/) was built by the fine folks at Google. Bazel manages dependency
downloads, generates the Selenium binaries, executes tests and does it all rather quickly.

More detailed instructions for getting Bazel running are below, but if you can successfully get
the java and javascript folders to build without errors, you should be confident that you have the
correct binaries on your system.

### Before Building

Ensure that you have Chrome installed and the
[`chromedriver` ](https://sites.google.com/a/chromium.org/chromedriver/downloads) that matches
your Chrome version available on your `$PATH`. You may have to update this from time to time.

To build Selenium, in the same directory as this file:
### Common Build Targets

```sh
./go build
```

The order of building modules is determined by the build system.
If you want to build an individual module
(assuming all dependent modules have previously been built),
try the following:
To build the most commonly-used modules of Selenium from source, execute this command from the root
project folder:

```sh
./go //javascript/atoms:test:run
bazel build java/...
```

In this case, `javascript/atoms` is the module directory,
`test` is a target in that directory's `build.desc` file,
and `run` is the action to run on that target.

As you see *build targets* scroll past in the log,
you may want to run them individually.
crazyfun can run them individually,
by target name, as long as `:run` is appended (see above).

To list all available targets, you can append the `-T` flag:
If you have some extra time on your hands, you can run this command to get extra confidence
that your build is successful. This will do a lot more work to build all the javascript artifacts:

```sh
./go -T
bazel build java/... javascript/...
```

### Buck
If you're making changes to the java/ or javascript/ folders in this project, and this command
executes without errors, you should be able to create a PR of your changes. (See also CONTRIBUTING.md)

Although the plan is to return to a vanilla build of Buck as soon as
possible, we currently use a fork hosted at
https://github.com/SeleniumHQ/buck
### Build Details ###

Selenium uses `buckw` wrapper utility that automatically downloads buck if necessary and runs it with the specified options.
- Bazel files are called BUILD.bazel
- [crazyfun](https://github.com/SeleniumHQ/selenium/wiki/Crazy-Fun-Build) build files are called
*build.desc*. This is an older build system, still in use in the project
- There is also a main Rakefile

To obtain a list of all available targets:
The order the modules are built is determined by the build system. If you want to build an
individual module (assuming all dependent modules have previously been built), try the following:

```sh
buckw targets
./go javascript/atoms:test:run
```

And build a particular file:
In this case, `javascript/atoms` is the module directory,
`test` is a target in that directory's `build.desc` file,
and `run` is the action to run on that target.

```sh
buckw build //java/client/src/org/openqa/selenium:webdriver-api
```
As you see *build targets* scroll past in the log,
you may want to run them individually. crazyfun can run them individually,
by target name, as long as `:run` is appended (see above).

There are aliases for commonly invoked targets in the `.buckconfig`
file, and these aliases can be invoked directly:
To list all available targets, you can append the `-T` flag:

```sh
buckw build htmlunit
./go -T
```

All buck output is stored under "buck-out", with the outputs of build
rules in `buck-out/gen`.

If you are doing a number of incremental builds, then you may want to
use `buckd`, which starts a long-lived buck process to watch outputs
and input files. If you do this, consider using `watchman` too, since
the Java 7 file watcher isn't terribly efficient. This can be cloned
from https://github.com/facebook/watchman

## Requirements

* [Java 8 JDK](http://www.oracle.com/technetwork/java/javase/downloads/index.html)
* `java` and `jar` on the PATH (make sure you use `java` executable from JDK but not JRE)
* [Python 2.7](https://www.python.org/)
* `python` on the PATH (make sure it's Python 2.7, as buck build tool is not Python 3 compatible)
* The latest version of the [Java 11 OpenJDK](http://www.oracle.com/technetwork/java/javase/downloads/index.html)
* `java` and `jar` on the PATH (make sure you use `java` executable from JDK but not JRE).
* To test this, try running the command `javac`. This command won't exist if you only have the JRE
installed. If you're met with a list of command-line options, you're referencing the JDK properly.
* [Python](https://www.python.org/)
* `python` on the PATH
* [The Requests Library](http://python-requests.org) for Python: `pip install requests`
* MacOS users should have XCode installed
* MacOS users should have the latest version of XCode installed, including the command-line tools.
The following command should work:

```bash
xcode-select --install
```

Although the build system is based on rake, it's **strongly advised**
to rely on the version of JRuby in `third_party/` that is invoked by
`go`. The only developer type who would want to deviate from this is
the “build maintainer” who's experimenting with a JRuby upgrade.

Note that all Selenium Java artifacts are **built with Java 8
(mandatory)**. Those _will work with any Java >= 8_.

### Optional Requirements

* Python 3.4+ (if you want to run Python tests for this version)
Expand All @@ -148,79 +138,31 @@ you also need:
The build will work on any platform, but the tests for IE will be
skipped silently if you are not building on Windows.

## Common Tasks
## Common Tasks (Bazel)

For an express build of the binaries we release, run the following from
the directory containing the `Rakefile`:
To build the bulk of the Selenium binaries from source, run the
following command from the root folder:

```sh
./go release
bazel build java/... javascript/...
```

All build output is placed under the `build` directory. The output can
be found under `build/dist`. If an error occurs while running this
task complaining about a missing Albacore gem, chances are you're
using `rvm`. If this is the case, switch to the system ruby:
To build the grid deployment jar, run this command:

```sh
rvm system
bazel build grid
```

Of course, building the entire project can take too long. If you just
want to build a single driver, then you can run one of these targets:
To run tests within a particular area of the project, use the "test" command, followed
by the folder or target. Tests are tagged with "small", "medium", or "large", and can be filtered
with the `--test_size_filters` option:

```sh
./go chrome
./go firefox
./go ie
bazel test --test_size_filters=small,medium java/...
```

As the build progresses, you'll see it report where the build outputs
are being placed. Of course, just building isn't enough. We should
really be able to run the tests too. Try:

```sh
./go test_chrome
./go test_firefox
./go test_htmlunit
./go test_ie
./go test_edge
```

Note that the `test_chrome` target requires that you have the separate
[Chrome Driver](https://github.com/SeleniumHQ/selenium/wiki/ChromeDriver)
binary available on your `PATH`.

`test_edge` target requires that you have separated [Edge Driver](https://developer.microsoft.com/en-us/microsoft-edge/tools/webdriver) binary available on your `PATH`.

If you are interested in a single language binding, try one of:

```sh
./go test_java
./go test_dotnet
./go test_rb
./go test_javascript
```

To run all the tests, run:

```sh
./go test
```

This will detect your OS and run all the tests that are known to be
stable, for every browser that's appropriate to use, for all language
bindings. This can take a healthy amount of time to run.

To run the minimal logical Selenium build:

```sh
./go test_javascript test_java
```

As a side note, **none of the developers** run tests using
[Cygwin](http://www.cygwin.com/). It is very unlikely that the build
will work as expected if you try to use it.
Bazel's "test" command will run *all* tests in the package, including integration tests. Expect
the ```test java/...``` to launch browsers and consume a considerable amount of time and resources.

## Tour

Expand Down Expand Up @@ -293,9 +235,8 @@ targets.
## Maven _per se_

If it is not clear already, Selenium is not built with Maven. It is
built with [Buck](https://github.com/SeleniumHQ/buck),
though that is invoked with `go` as outlined above, so you do not really
have to learn too much about that.
built with `bazel`, though that is invoked with `go` as outlined above,
so you do not really have to learn too much about that.

That said, it is possible to relatively quickly build Selenium pieces
for Maven to use. You are only really going to want to do this when
Expand All @@ -308,19 +249,49 @@ skipping Selenium's own tests.
./go maven-install
```

The maven jars should now be in your local `~/.m2/repository`. You can also publish
directly using Buck:

```sh
buckw publish -r your-repo //java/client/src/org/openqa/selenium:selenium
```

This sequence will push some seven or so jars into your local Maven
repository with something like 'selenium-server-3.0.0.jar' as
the name.
The maven jars should now be in your local `~/.m2/repository`.

## Useful Resources

Refer to the [Building Web
Driver](https://github.com/SeleniumHQ/selenium/wiki/Building-WebDriver)
wiki page for the last word on building the bits and pieces of Selenium.

## Bazel Installation/Troubleshooting

### MacOS

#### bazelisk

Bazelisk is a Mac-friendly launcher for Bazel. To install, follow these steps:

```sh
brew tap bazelbuild/tap && \
brew uninstall bazel; \
brew install bazelbuild/tap/bazelisk
```

#### XCode

If you're getting errors that mention XCode, you'll need to install the command-line tools.

Bazel for Mac requires some additional steps to configure properly. First things first: use
the Bazelisk project (courtesy of philwo), a pure golang implementation of Bazel. In order to
install Bazelisk, first verify that your XCode will cooperate: execute the following command:

`xcode-select -p`

If the value is `/Applications/Xcode.app/Contents/Developer/`, you can proceed with bazelisk
installation. If, however, the return value is `/Library/Developer/CommandLineTools/`, you'll
need to redirect the XCode system to the correct value.

```
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer/
sudo xcodebuild -license
```

The first command will prompt you for a password. The second step requires you to read a new XCode
license, and then accept it by typing "agree".

(Thanks to [this thread](https://github.com/bazelbuild/bazel/issues/4314) for these steps)

0 comments on commit 38cd7bc

Please sign in to comment.