scratchjr/README.md

## Overview
This is the official git repository hosting the source code for the
[ScratchJr](http://scratchjr.org/) project.

ScratchJr can be built both for iOS and Android.
A pure-web version is planned to follow at some point in the future.

Platform | Status
-------- | -------------
iOS      | Released in App Store
Android  | Released in Google Play

## Architecture Overview
The diagram below illustrates the architecture of ScratchJr and
how the iOS (functional), Android (functional) and pure HTML5 (future)
versions share a common client.

![Scratch Jr. Architecture Diagram](doc/scratchjr_architecture.png)


## Directory Structure and Projects
This repository has the following directory structure:

* <tt>src/</tt> - Shared JavaScript code for iOS and Android common client. This is where most changes should be made for features, bug fixes, UI, etc.
* <tt>editions/</tt> - Assembly directories for each "flavor" of ScratchJr. These symlink to src for common code, and could diverge in settings and assets.
  * <tt>free/</tt> - Free edition JavaScript, including all shared code for all releases
* <tt>android/</tt> - Android port of Scratch Jr. (Java, Android Studio Projects)
  * <tt>ScratchJr/</tt> - Android Studio Project for ScratchJr Android Application
* <tt>bin/</tt> - Build scripts and other executables
* <tt>doc/</tt> - Developer Documentation
* <tt>ios/</tt> - Xcode project for iOS build. (Make sure to open <tt>ScratchJr.xcworkspace</tt> not <tt>ScratchJr.xcodeproj</tt>)

## Building ScratchJr

### Initial setup

Regardless of whether you are doing iOS development or Android development, you should do these steps.

*These instructions assume you are building both versions on Mac OSX, with [Homebrew](http://brew.sh) installed.*

1. Clone or update the code for this repo
2. Ensure you have node and npm [installed](https://www.npmjs.com/get-npm).
3. Run <tt>sudo easy_install pysvg</tt> to install python svg libraries
4. Run <tt>brew install librsvg</tt> to install commandline `rsvg-convert`
5. Run <tt>brew install imagemagick</tt> to install commandline `magick`
6. In the top level of the scratchjr repo directory, install npm dependencies for bundling the JavaScript: <tt>npm install</tt>

### Analytics
ScratchJr uses the Firebase SDK to record analytics for the app. Scratch Team developers should look for
the configuration files in the Scratch Devs Vault. If you're not on the Scratch Team, then you'll need to
set up your own [app analytics](https://firebase.google.com/products/analytics) with Google Firebase. It's free. Firebase will generate the configuration files for you to download.

1. Place the `google-services.json` file in `editions/free/android-resources`
2. Place the `GoogleService-Info.plist` file in `editions/free/ios-resources`

### iOS

1. To build the iOS version, you need to have a Mac with Xcode
2. Run <tt>brew install cocoapods</tt> to install CocoaPods
3. Run <tt>pod install</tt> to install the Firebase Analytics dependencies
4. Open Xcode
5. In Xcode, open <tt>ios/ScratchJr.xcworkspace</tt>

### Android

1. Install or update Android Studio
2. In Android Studio, open the project <tt>android/ScratchJr</tt>
3. Choose the appropriate flavor/build variant in Android Studio

*Note: you can still do Android development on Ubuntu. Instead of the install commands above, run:*

1. <tt>sudo easy_install pysvg</tt> to install python svg libraries
2. <tt>sudo apt-get install librsvg2-bin</tt> to install rsvg-convert
3. <tt>sudo apt-get install imagemagick</tt> to install ImageMagick

## Where and how to make changes

All changes should be made in a fork. Before making a pull request, ensure all changes pass our linter:
* <tt>npm run lint</tt>

For more information, see [CONTRIBUTING.md](https://github.com/LLK/scratchjr/blob/develop/.github/CONTRIBUTING.md).

## Code credits
ScratchJr would not be possible without free and open source libraries, including:
* [Snap.svg](https://github.com/adobe-webplatform/Snap.svg/)
* [JSZip](https://github.com/Stuk/jszip)
* [Intl.js](https://github.com/andyearnshaw/Intl.js)
* [Yahoo intl-messageformat](https://github.com/yahoo/intl-messageformat)

## Acknowledgments
ScratchJr is a collaborative effort between:

* [Tufts DevTech Research Group](http://ase.tufts.edu/devtech/)
* [Lifelong Kindergarten group at MIT Media Lab](http://llk.media.mit.edu/)
* [Playful Invention Company](http://www.playfulinvention.com/)
* [Two Sigma Investments](http://twosigma.com)
Initial commit 2016-01-08 14:31:04 -05:00			`## Overview`
			`This is the official git repository hosting the source code for the`
			`[ScratchJr](http://scratchjr.org/) project.`

License, CONTRIBUTING, update README, package.json 2016-02-09 12:49:21 -05:00			`ScratchJr can be built both for iOS and Android.`
Improve Analytics setup documentation Added instructions to the README for how to get the google services configuration files for analytics. Removed (and ignored in future) the empty config files. Note: empty folders are ignored in git, so added an empty file `.exist` to the android folder so that it will be there as a place to hold the actual google services file. Finally added the xCode scheme for the app that you need for newer versions of xCode. 2020-03-24 17:31:16 -04:00			`A pure-web version is planned to follow at some point in the future.`
Initial commit 2016-01-08 14:31:04 -05:00
			`Platform \| Status`
			`-------- \| -------------`
			`iOS \| Released in App Store`
Improve Analytics setup documentation Added instructions to the README for how to get the google services configuration files for analytics. Removed (and ignored in future) the empty config files. Note: empty folders are ignored in git, so added an empty file `.exist` to the android folder so that it will be there as a place to hold the actual google services file. Finally added the xCode scheme for the app that you need for newer versions of xCode. 2020-03-24 17:31:16 -04:00			`Android \| Released in Google Play`
Initial commit 2016-01-08 14:31:04 -05:00
			`## Architecture Overview`
			`The diagram below illustrates the architecture of ScratchJr and`
			`how the iOS (functional), Android (functional) and pure HTML5 (future)`
			`versions share a common client.`

			`![Scratch Jr. Architecture Diagram](doc/scratchjr_architecture.png)`


			`## Directory Structure and Projects`
			`This repository has the following directory structure:`

Clean-Up 2017-09-25 07:24:45 -04:00			`* <tt>src/</tt> - Shared JavaScript code for iOS and Android common client. This is where most changes should be made for features, bug fixes, UI, etc.`
Initial commit 2016-01-08 14:31:04 -05:00			`* <tt>editions/</tt> - Assembly directories for each "flavor" of ScratchJr. These symlink to src for common code, and could diverge in settings and assets.`
Update README.md 2017-05-05 11:39:07 -04:00			`* <tt>free/</tt> - Free edition JavaScript, including all shared code for all releases`
Initial commit 2016-01-08 14:31:04 -05:00			`* <tt>android/</tt> - Android port of Scratch Jr. (Java, Android Studio Projects)`
			`* <tt>ScratchJr/</tt> - Android Studio Project for ScratchJr Android Application`
			`* <tt>bin/</tt> - Build scripts and other executables`
			`* <tt>doc/</tt> - Developer Documentation`
Address comments Use correct (and consisten) capitalization for ‘Xcode’. Clarify that Firebase generates config files. 2020-03-30 11:27:15 -04:00			`* <tt>ios/</tt> - Xcode project for iOS build. (Make sure to open <tt>ScratchJr.xcworkspace</tt> not <tt>ScratchJr.xcodeproj</tt>)`
Initial commit 2016-01-08 14:31:04 -05:00
			`## Building ScratchJr`

reorganized android and ios setup steps 2020-03-23 12:14:24 -04:00			`### Initial setup`
License, CONTRIBUTING, update README, package.json 2016-02-09 12:49:21 -05:00
reorganized android and ios setup steps 2020-03-23 12:14:24 -04:00			`Regardless of whether you are doing iOS development or Android development, you should do these steps.`
License, CONTRIBUTING, update README, package.json 2016-02-09 12:49:21 -05:00
reorganized android and ios setup steps 2020-03-23 12:14:24 -04:00			`These instructions assume you are building both versions on Mac OSX, with [Homebrew](http://brew.sh) installed.`
Initial commit 2016-01-08 14:31:04 -05:00
reorganized android and ios setup steps 2020-03-23 12:14:24 -04:00			`1. Clone or update the code for this repo`
Update README.md link to the current info for installing node and npm 2021-05-04 16:59:50 -04:00			`2. Ensure you have node and npm [installed](https://www.npmjs.com/get-npm).`
reorganized android and ios setup steps 2020-03-23 12:14:24 -04:00			`3. Run <tt>sudo easy_install pysvg</tt> to install python svg libraries`
			4. Run <tt>brew install librsvg</tt> to install commandline `rsvg-convert`
			5. Run <tt>brew install imagemagick</tt> to install commandline `magick`
			`6. In the top level of the scratchjr repo directory, install npm dependencies for bundling the JavaScript: <tt>npm install</tt>`
Initial commit 2016-01-08 14:31:04 -05:00
Improve Analytics setup documentation Added instructions to the README for how to get the google services configuration files for analytics. Removed (and ignored in future) the empty config files. Note: empty folders are ignored in git, so added an empty file `.exist` to the android folder so that it will be there as a place to hold the actual google services file. Finally added the xCode scheme for the app that you need for newer versions of xCode. 2020-03-24 17:31:16 -04:00			`### Analytics`
			`ScratchJr uses the Firebase SDK to record analytics for the app. Scratch Team developers should look for`
			`the configuration files in the Scratch Devs Vault. If you're not on the Scratch Team, then you'll need to`
Address comments Use correct (and consisten) capitalization for ‘Xcode’. Clarify that Firebase generates config files. 2020-03-30 11:27:15 -04:00			`set up your own [app analytics](https://firebase.google.com/products/analytics) with Google Firebase. It's free. Firebase will generate the configuration files for you to download.`
Improve Analytics setup documentation Added instructions to the README for how to get the google services configuration files for analytics. Removed (and ignored in future) the empty config files. Note: empty folders are ignored in git, so added an empty file `.exist` to the android folder so that it will be there as a place to hold the actual google services file. Finally added the xCode scheme for the app that you need for newer versions of xCode. 2020-03-24 17:31:16 -04:00
			1. Place the `google-services.json` file in `editions/free/android-resources`
			2. Place the `GoogleService-Info.plist` file in `editions/free/ios-resources`

reorganized android and ios setup steps 2020-03-23 12:14:24 -04:00			`### iOS`
Initial commit 2016-01-08 14:31:04 -05:00
Address comments Use correct (and consisten) capitalization for ‘Xcode’. Clarify that Firebase generates config files. 2020-03-30 11:27:15 -04:00			`1. To build the iOS version, you need to have a Mac with Xcode`
reorganized android and ios setup steps 2020-03-23 12:14:24 -04:00			`2. Run <tt>brew install cocoapods</tt> to install CocoaPods`
			`3. Run <tt>pod install</tt> to install the Firebase Analytics dependencies`
Address comments Use correct (and consisten) capitalization for ‘Xcode’. Clarify that Firebase generates config files. 2020-03-30 11:27:15 -04:00			`4. Open Xcode`
			`5. In Xcode, open <tt>ios/ScratchJr.xcworkspace</tt>`
Initial commit 2016-01-08 14:31:04 -05:00
reorganized android and ios setup steps 2020-03-23 12:14:24 -04:00			`### Android`
Initial commit 2016-01-08 14:31:04 -05:00
reorganized android and ios setup steps 2020-03-23 12:14:24 -04:00			`1. Install or update Android Studio`
			`2. In Android Studio, open the project <tt>android/ScratchJr</tt>`
			`3. Choose the appropriate flavor/build variant in Android Studio`

			`Note: you can still do Android development on Ubuntu. Instead of the install commands above, run:`

			`1. <tt>sudo easy_install pysvg</tt> to install python svg libraries`
			`2. <tt>sudo apt-get install librsvg2-bin</tt> to install rsvg-convert`
			`3. <tt>sudo apt-get install imagemagick</tt> to install ImageMagick`
Initial commit 2016-01-08 14:31:04 -05:00
License, CONTRIBUTING, update README, package.json 2016-02-09 12:49:21 -05:00			`## Where and how to make changes`

			`All changes should be made in a fork. Before making a pull request, ensure all changes pass our linter:`
			`* <tt>npm run lint</tt>`

Corrected the link for CONTRIBUTING.md 2021-08-23 00:45:31 -04:00			`For more information, see [CONTRIBUTING.md](https://github.com/LLK/scratchjr/blob/develop/.github/CONTRIBUTING.md).`
License, CONTRIBUTING, update README, package.json 2016-02-09 12:49:21 -05:00
Initial commit 2016-01-08 14:31:04 -05:00			`## Code credits`
			`ScratchJr would not be possible without free and open source libraries, including:`
			`* [Snap.svg](https://github.com/adobe-webplatform/Snap.svg/)`
			`* [JSZip](https://github.com/Stuk/jszip)`
			`* [Intl.js](https://github.com/andyearnshaw/Intl.js)`
			`* [Yahoo intl-messageformat](https://github.com/yahoo/intl-messageformat)`

			`## Acknowledgments`
			`ScratchJr is a collaborative effort between:`

			`* [Tufts DevTech Research Group](http://ase.tufts.edu/devtech/)`
			`* [Lifelong Kindergarten group at MIT Media Lab](http://llk.media.mit.edu/)`
			`* [Playful Invention Company](http://www.playfulinvention.com/)`
			`* [Two Sigma Investments](http://twosigma.com)`