diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 000000000..a2677dec6 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,15 @@ +# Set the default behavior in the event that core.autocrlf is not set +* text eol=lf + +*.dbf binary +*.gif binary +*.gpx binary +*.ico binary +*.jpg binary +*.kmz binary +*.pdf binary +*.png binary +*.shp binary +*.woff binary +*.woff2 binary +*.zip binary diff --git a/README.md b/README.md index 230038f05..dcb05b36f 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ Questions? Ask them in the [forum](https://groups.google.com/forum/#!forum/opens * Node/NPM ## Getting Started -OpenSphere is natively developed on Linux and should run great on OS X and typical Linux distributions. Windows support is limited, as the build system requires a Linux shell. Windows 10 introduced the Windows Subsystem for Linux (WSL) which works great, see [here](windows.md) for instructions on setting up a Windows 10/WSL environment to work on OpenSphere projects. Other Windows distributions, perhaps try Cygwin or Linux via a VM or Docker container. +OpenSphere is natively developed on Linux and should run great on OS X and typical Linux distributions. See [Windows Development](http://opensphere.readthedocs.io/en/latest/windows_development.html) for instructions for building on Windows. ### Yarn @@ -111,7 +111,7 @@ By default the ```baseURL``` is set to the local compiled build: http://localhos ### Running Tests Run all tests via the command line ```yarn test:cypress-all```, individual specs via the command line ```yarn test:cypress-spec folder/test.spec.js```, or run tests interactively with the [Test Runner](https://docs.cypress.io/guides/core-concepts/test-runner.html) via ```yarn test:cypress```. - + ### Adding and modifying tests diff --git a/docs/getting_started.rst b/docs/getting_started.rst index 363a23f4b..4e3494ec3 100644 --- a/docs/getting_started.rst +++ b/docs/getting_started.rst @@ -21,7 +21,10 @@ Prerequisites - Chrome Browser (59+ required in default tests; plus you probably want this for development) - Firefox Browser (57+ required in default tests) +Windows developers see `Windows Development`_ + .. _Yarn: https://yarnpkg.com +.. _Windows Development: windows_development.html Ensure that the executables ``git``, ``node``, and ``java`` are in your ``PATH``. @@ -71,7 +74,7 @@ While not required, we highly recommend setting up nginx or Apache httpd to serv The Build ********* -Note: The build does not work in Windows. Consider using an Ubuntu Docker container or VM to run the build. +Note: The build does not work natively in Windows. See `Windows Development`_ for instructions. OpenSphere has all of its build targets as npm scripts. Therefore you can run any particular target by running: @@ -165,9 +168,9 @@ Any contributions to OpenSphere should avoid breaking current tests and should i Git Commits *********** -When making local commits, there are checks (implemented as git pre-commit hooks) to verify that your commit message matches the `Conventional Commits`_ conventions. +When making local commits, there are checks (implemented as git pre-commit hooks) to verify that your commit message matches the `Conventional Commits`_ conventions. Basically, you need use the form ``(): ``, for example something like: ``fix(docs): Updated Getting Started to describe git commits``. -The valid types are: ``feat``, ``fix``, ``docs``, ``style``, ``refactor``, ``perf``, ``test``, ``build``, ``ci``, ``chore`` and ``revert``. Scope is optional, and +The valid types are: ``feat``, ``fix``, ``docs``, ``style``, ``refactor``, ``perf``, ``test``, ``build``, ``ci``, ``chore`` and ``revert``. Scope is optional, and should cover the particular part of opensphere that you are working on. .. _Conventional Commits: https://www.conventionalcommits.org @@ -209,6 +212,7 @@ The compiler will attempt to minify/rename everything not in a string. For the m Broken Example: .. code-block:: javascript + :linenos: /** * @param {!angular.Scope} $scope The scope @@ -225,6 +229,7 @@ Broken Example: }; .. code-block:: html + :linenos: {{value}} is positive @@ -234,6 +239,8 @@ This will work great in debug mode (no minification), but will fail in compiled Fixed Example: .. code-block:: javascript + :linenos: + :emphasize-lines: 5, 10 /** * @param {!angular.Scope} $scope The scope @@ -244,14 +251,14 @@ Fixed Example: /** * @param {number} value + * @export */ package.DirCtrl.prototype.isPositive = function(value) { return value > 0; }; - // we highly recommend making this a snippet - goog.exportProperty(package.DirCtrl.prototype, 'isPositive', package.DirCtrl.prototype.isPositive); .. code-block:: html + :linenos: {{value}} is positive diff --git a/docs/index.rst b/docs/index.rst index fc2b01e0f..2c3411b3e 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -23,6 +23,7 @@ The code is open source, and `available on GitHub`_. contributing getting_started + windows_development guides/app_guide guides/plugin_guide guides/settings_guide diff --git a/docs/windows_development.rst b/docs/windows_development.rst new file mode 100644 index 000000000..433247907 --- /dev/null +++ b/docs/windows_development.rst @@ -0,0 +1,86 @@ +.. _windows_development: + +Windows Development +################### + +Our build does not run natively on Windows due to its requirement of a POSIX shell and some of +the core utilities such as ``cat``, ``cp``, ``echo``, ect. However, you can build and develop +OpenSphere on Windows with any of the following: + +- Git Bash (included with Git for Windows) +- Cygwin_ +- `Windows Subsystem for Linux`_ +- Docker +- Linux VM + +These instructions will take the simplest approach by using Git Bash. + +.. _Cygwin: https://www.cygwin.com +.. _Windows Subsystem for Linux: https://docs.microsoft.com/en-us/windows/wsl/install-win10 + + +Prerequisites +============= + +Install git, java, node, and yarn. We recommend using Chocolatey_, a package manager for Windows. +After installing Chocolatey_, run the following in a command prompt as an administrator: + +.. _Chocolatey: https://chocolatey.org/ + +.. code-block:: none + + choco install git jre8 nvm yarn + refreshenv + nvm install 10.16.2 + nvm use 10.16.2 + +Now we will check our work: + +.. code-block:: none + + git --version + java -version + node --version + npm --version + yarn --version + +Git for Windows installs "Git Bash". Search for it in the Start Menu and fire it up. + + +Setup +===== + +Setup the project workspace and clone the project: + +.. code-block:: none + + cd + git clone https://github.com/ngageoint/opensphere-yarn-workspace + cd opensphere-yarn-workspace/workspace + git clone https://github.com/ngageoint/opensphere + yarn install + cd opensphere + +Now you are about ready to build opensphere. However, we need to tell the NPM script runner to use BASH +rather than whatever it typically uses on Windows. + +.. code-block:: none + + npm config set script-shell "C:/Program Files/git/bin/bash.exe" + +If you have other node projects on your machine and do not wish for this to pollute them, then consider adding +that configuration to a ``.npmrc`` file local to the project. + +Also fix your line ending configuration for git (necessary if using Git Bash but not if you are using a full POSIX environment such as Cygwin_): + +.. code-block:: none + + git config core.autocrlf input + +Now build: + +.. code-block:: none + + npm run build + +At the time of this writing, ``yarn`` has a bug with the ``script-shell`` config. A fix has already been committed and should make their next non-patch release. After that you can use ``yarn run build`` or just ``yarn build`` if you prefer. diff --git a/windows.md b/windows.md deleted file mode 100644 index 203909235..000000000 --- a/windows.md +++ /dev/null @@ -1,118 +0,0 @@ -# Running/Developing OpenSphere on Windows 10+ - -The following are instructions for getting OpenSphere building and running on a Windows 10 system using the new Windows Subsystem for Linux (WSL). Note All of the following instructions assume a Windows 10 build of 16215 or later. - -## Installing WSL - -See the following instructions for setting up WSL on Windows 10. - -https://docs.microsoft.com/en-us/windows/wsl/install-win10 - -After installing the WSL feature and selecting a distribution, the following OpenSphere project prerequisites need to be installed using the WSL shell environment. - -* [git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) -* [NodeJS 8](https://nodejs.org/en/download/package-manager/) -* Oracle Java 8 SDK, OpenJDK should also work -* [Ubuntu](https://www.digitalocean.com/community/tutorials/how-to-install-java-with-apt-get-on-ubuntu-16-04) -* [Open SUSE](https://en.opensuse.org/SDB:Installing_Java) -* [Yarn](https://yarnpkg.com/lang/en/docs/install/#linux-tab) - -After all prerequisites have been installed and verified, the OpenSphere getting started instructions should work. - -## Working with Windows - -The WSL environment has convenient mounts for all of the windows drives, so it easy to share files/folders with WSL and Windows by utilizing the drive mounts in WSL `/mnt//`. For example, you could configured the following path in Windows for the OpenSphere related projects: - -`c:\source\ngageoint` - -## Opening a WSL shell - -The windows WSL environment can be opened in a few ways, open a normal command prompt/PowerShell and just type wsl. Alternatively, find the distro or "wsl" from the start menu and run. This should open the WSL shell. - -## Cloning OpenSphere - -From within the (WSL) shell, cd to your working directory. Using the example, this would be cd `/mnt/c/source/ngageoint` - -From this point forward, we can follow the Getting Started instructions provided by the OpenSphere project. - -* Fork/Clone the https://github.com/ngageoint/opensphere project in your project working directory `/mnt/c/source/ngageoint` -* Fork/Clone the https://github.com/ngageoint/opensphere-yarn-workspace project to your working directory `/mnt/c/source/ngageoint` - -### Windows/Git - -Git commands can be done from either Windows dos/powershell or WSL environment, however, be aware of Operating System end of line differences. Linux and Windows use different end of line markers, it's strongly recommend that the following commands be run from within each OpenSphere project to ensure files do not get changed by git/windows. - -``` -git config core.eol lf -git config core.autocrlf false -``` - -## Setting up the OpenSphere workspace - -Now that the projects are cloned and ready, all `npm/node/yarn` related commands should be run from the WSL environment. - -Following the example: -``` -cd /mnt/c/source/ngageoint/opensphere -yarn install -npm run build -```` - -## Hosting - -See the OpenSphere readme about locally hosting the OpenSphere application. - -## Editing - -If the project was checked out to one of the /mnt/? folders, then all of the files for the project are living on the Windows file system! Pick your favorite code editor/IDE and go to work. - -Please be aware of the coding styles and linux/windows end of line differences. Most modern IDE's have options to specify preferences. - -Otherwise, use the WSL terminal to run project related commands, and code editing in your Windows editor of choice. - -## Using VSCode -[Visual Studio Code](https://code.visualstudio.com/) Is a free multi-platform open source code editor with a lot of handy features.This IDE is actually pretty good (maybe not prefect, but I like it). One feature that is very useful for projects like OpenSphere, is a way to define a preferred integrated terminal environment, like WSL terminal on Windows, see: https://blogs.msdn.microsoft.com/commandline/2017/10/27/running-node-js-on-wsl-from-visual-studio-code/ - -For those of you who have adopted VSCode and are working on this project, the following things should be done to make the experience a bit better. - -### Plugins - -Install the following plugins: -* ESLint -* Beautify - -Other handy plugin(s:) -* Git Lens - -### Workspace -Visual Studio Code support "[Workspaces](https://code.visualstudio.com/docs/editor/multi-root-workspaces)" configuration files. As OpenSphere is a likely candidate for a multi-root workspace project, this is a useful feature. - -The following is a workspace file that defines a number of settings that are consistent with the OpenSphere baseline. The contents of the following can be copied to a file called ``` opensphere.code-workspace ```, located at the workspace level of the project. - -``` -{ - "folders": [ - { - "path": "." - } - ], - "settings": { - "editor.tabSize": 2, - "files.autoSave": "afterDelay", - "files.autoSaveDelay": 1000, - "terminal.integrated.shell.windows": "wsl.exe", - "eslint.enable": true, - "eslint.autoFixOnSave": true, - "files.exclude": { - "**/.git": true, - "**/.svn": true, - "**/.hg": true, - "**/CVS": true, - "**/.DS_Store": true, - "**/.build": true, - "**/node_modules": true, - "**/dist": true - } - } -} -```