Android studio: new project vs new module

Question

KISS answer:

module in Android Studio is like a project in Eclipse

project in Android Studio is like a workspace in Eclipse

From the documentation (Android Studio is based on Intellij IDEA) :

Whatever you do in IntelliJ IDEA, you do that in the context of a project. A project is an organizational unit that represents a complete software solution.

Your finished product may be decomposed into a series of discrete, isolated modules, but it's a project definition that brings them together and ties them into a greater whole.

For Android, it means one project per app, and one module per library and per test app.

There are multiple issues if you try to build multiple apps within the same project. It's possible, but if you try (like I did), you will see that almost everything is designed to work with a single app per project.

For example, there is an option to "rebuild the project", which makes no sense with multiple apps, many other project settings would be useless, and the built-in VCS system isn't great when you have multiple repositories.

A project in Android Studio represents a complete Android app. Android Studio projects consist of one or more modules.

A module is a component of your app that you can build, test, or debug independently.

Modules contain the source code and resources for your app.

From updated docs [2019]:

Modules provide a container for your app's source code, resource files, and app level settings, such as the module-level build file and Android manifest file. Each module can be independently built, tested, and debugged.

Android Studio uses modules to make it easy to add new devices to your project. By following a few simple steps in Android Studio, you can create a module to contain code that's specific to a device type, such as Wear OS or Android TV. Android Studio automatically creates module directories, such as source and resource directories, and a default build.gradle file appropriate for the device type. Also, Android Studio creates device modules with recommended build configurations, such as using the Leanback library for Android TV modules.

Ex:

• Phone & Tablet Module
• Android Wear Module
• Android TV Module
• Glass Module

Besides these, you can also have a "local library module". Say, you develop a Account Management Framework as a library module to be used ultimately in your App, you can do it as a separate module in the same project. To include that in your App, you would have to write something like,

compile project(':mylibrary')

Docs say,

This declares a dependency on an Android library module named "mylibrary" (this name must match the library name defined as an include in your settings.gradle file). It requires the build system to compile the library module with your app module and include the resulting AAR file in your APK.

Lastly, Intellij mentions some more details about Module configuration files:

Configuration information for a module is stored in a .iml module file. By default, such a file is located in the module's content root folder.

Development teams, normally, share the .iml module files through version control.

This .iml file is a bit scary to look at. Here is an example from my project:

<?xml version="1.0" encoding="UTF-8"?>
<module external.linked.project.id=":app" external.linked.project.path="$MODULE_DIR$" external.root.project.path="$MODULE_DIR$/.." external.system.id="GRADLE" external.system.module.group="LearnCity" external.system.module.version="unspecified" type="JAVA_MODULE" version="4">
  <component name="FacetManager">
    <facet type="android-gradle" name="Android-Gradle">
      <configuration>
        <option name="GRADLE_PROJECT_PATH" value=":app" />
      </configuration>
    </facet>
    <facet type="android" name="Android">
      <configuration>
        <option name="SELECTED_BUILD_VARIANT" value="debug" />
        <option name="ASSEMBLE_TASK_NAME" value="assembleDebug" />
        <option name="COMPILE_JAVA_TASK_NAME" value="compileDebugSources" />
        <afterSyncTasks>
          <task>generateDebugSources</task>
        </afterSyncTasks>
        <option name="ALLOW_USER_CONFIGURATION" value="false" />
        <option name="MANIFEST_FILE_RELATIVE_PATH" value="/src/main/AndroidManifest.xml" />
        <option name="RES_FOLDER_RELATIVE_PATH" value="/src/main/res/layouts/common/layout/ver3/layout" />
        <option name="RES_FOLDERS_RELATIVE_PATH" value="file://$MODULE_DIR$/src/main/res/layouts/common/layout/ver3/layout;file://$MODULE_DIR$/src/main/res/layouts/common/layout/ver3;file://$MODULE_DIR$/src/main/res/layouts/common/layout/ver2/layout;file://$MODULE_DIR$/src/main/res/layouts/common/layout/ver2;file://$MODULE_DIR$/src/main/res/layouts/common/layout/ver1/layout;file://$MODULE_DIR$/src/main/res/layouts/common/layout/ver1;file://$MODULE_DIR$/src/main/res/layouts/common/layout/ver0/layout;file://$MODULE_DIR$/src/main/res/layouts/common/layout/ver0;file://$MODULE_DIR$/src/main/res/layouts/common/layout;file://$MODULE_DIR$/src/main/res/layouts/learner/layout;file://$MODULE_DIR$/src/main/res/layouts/tutor/layout;file://$MODULE_DIR$/src/main/res/layouts/obsolete/layout;file://$MODULE_DIR$/src/main/res/layouts/common;file://$MODULE_DIR$/src/main/res/layouts/learner;file://$MODULE_DIR$/src/main/res/layouts/tutor;file://$MODULE_DIR$/src/main/res/layouts/obsolete;file://$MODULE_DIR$/src/main/res/layouts;file://$MODULE_DIR$/src/main/res;file://$MODULE_DIR$/src/debug/res" />
        <option name="ASSETS_FOLDER_RELATIVE_PATH" value="/src/main/assets" />
      </configuration>
    </facet>
  </component>
  <component name="NewModuleRootManager" LANGUAGE_LEVEL="JDK_1_7" inherit-compiler-output="false">
    <output url="file://$MODULE_DIR$/build/intermediates/classes/debug" />
    <output-test url="file://$MODULE_DIR$/build/intermediates/classes/test/debug" />
    <exclude-output />
    <content url="file://$MODULE_DIR$">
      <sourceFolder url="file://$MODULE_DIR$/build/generated/source/r/debug" isTestSource="false" generated="true" />
      <sourceFolder url="file://$MODULE_DIR$/build/generated/source/aidl/debug" isTestSource="false" generated="true" />
      <sourceFolder url="file://$MODULE_DIR$/build/generated/source/buildConfig/debug" isTestSource="false" generated="true" />
      <sourceFolder url="file://$MODULE_DIR$/build/generated/source/rs/debug" isTestSource="false" generated="true" />
      <sourceFolder url="file://$MODULE_DIR$/build/generated/source/apt/debug" isTestSource="false" generated="true" />
      <sourceFolder url="file://$MODULE_DIR$/build/generated/res/google-services/debug" type="java-resource" />
      <sourceFolder url="file://$MODULE_DIR$/build/generated/res/rs/debug" type="java-resource" />
      <sourceFolder url="file://$MODULE_DIR$/build/generated/res/resValues/debug" type="java-resource" />
      <sourceFolder url="file://$MODULE_DIR$/build/generated/source/r/androidTest/debug" isTestSource="true" generated="true" />
      <sourceFolder url="file://$MODULE_DIR$/build/generated/source/aidl/androidTest/debug" isTestSource="true" generated="true" />
      <sourceFolder url="file://$MODULE_DIR$/build/generated/source/buildConfig/androidTest/debug" isTestSource="true" generated="true" />
      <sourceFolder url="file://$MODULE_DIR$/build/generated/source/rs/androidTest/debug" isTestSource="true" generated="true" />
      <sourceFolder url="file://$MODULE_DIR$/build/generated/source/apt/androidTest/debug" isTestSource="true" generated="true" />
      <sourceFolder url="file://$MODULE_DIR$/build/generated/res/rs/androidTest/debug" type="java-test-resource" />
      <sourceFolder url="file://$MODULE_DIR$/build/generated/res/resValues/androidTest/debug" type="java-test-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/debug/res" type="java-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/debug/resources" type="java-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/debug/assets" type="java-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/debug/aidl" isTestSource="false" />
      <sourceFolder url="file://$MODULE_DIR$/src/debug/java" isTestSource="false" />
      <sourceFolder url="file://$MODULE_DIR$/src/debug/rs" isTestSource="false" />
      <sourceFolder url="file://$MODULE_DIR$/src/debug/shaders" isTestSource="false" />
      <sourceFolder url="file://$MODULE_DIR$/src/testDebug/res" type="java-test-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/testDebug/resources" type="java-test-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/testDebug/assets" type="java-test-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/testDebug/aidl" isTestSource="true" />
      <sourceFolder url="file://$MODULE_DIR$/src/testDebug/java" isTestSource="true" />
      <sourceFolder url="file://$MODULE_DIR$/src/testDebug/rs" isTestSource="true" />
      <sourceFolder url="file://$MODULE_DIR$/src/testDebug/shaders" isTestSource="true" />
      <sourceFolder url="file://$MODULE_DIR$/src/main/res/layouts/common/layout/ver3/layout" type="java-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/main/res/layouts/common/layout/ver3" type="java-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/main/res/layouts/common/layout/ver2/layout" type="java-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/main/res/layouts/common/layout/ver2" type="java-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/main/res/layouts/common/layout/ver1/layout" type="java-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/main/res/layouts/common/layout/ver1" type="java-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/main/res/layouts/common/layout/ver0/layout" type="java-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/main/res/layouts/common/layout/ver0" type="java-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/main/res/layouts/common/layout" type="java-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/main/res/layouts/learner/layout" type="java-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/main/res/layouts/tutor/layout" type="java-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/main/res/layouts/obsolete/layout" type="java-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/main/res/layouts/common" type="java-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/main/res/layouts/learner" type="java-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/main/res/layouts/tutor" type="java-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/main/res/layouts/obsolete" type="java-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/main/res/layouts" type="java-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/main/res" type="java-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/main/resources" type="java-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/main/assets" type="java-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/main/aidl" isTestSource="false" />
      <sourceFolder url="file://$MODULE_DIR$/src/main/java" isTestSource="false" />
      <sourceFolder url="file://$MODULE_DIR$/src/main/rs" isTestSource="false" />
      <sourceFolder url="file://$MODULE_DIR$/src/main/shaders" isTestSource="false" />
      <sourceFolder url="file://$MODULE_DIR$/src/androidTest/res" type="java-test-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/androidTest/resources" type="java-test-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/androidTest/assets" type="java-test-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/androidTest/aidl" isTestSource="true" />
      <sourceFolder url="file://$MODULE_DIR$/src/androidTest/java" isTestSource="true" />
      <sourceFolder url="file://$MODULE_DIR$/src/androidTest/rs" isTestSource="true" />
      <sourceFolder url="file://$MODULE_DIR$/src/androidTest/shaders" isTestSource="true" />
      <sourceFolder url="file://$MODULE_DIR$/src/test/res" type="java-test-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/test/resources" type="java-test-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/test/assets" type="java-test-resource" />
      <sourceFolder url="file://$MODULE_DIR$/src/test/aidl" isTestSource="true" />
      <sourceFolder url="file://$MODULE_DIR$/src/test/java" isTestSource="true" />
      <sourceFolder url="file://$MODULE_DIR$/src/test/rs" isTestSource="true" />
      <sourceFolder url="file://$MODULE_DIR$/src/test/shaders" isTestSource="true" />
      <excludeFolder url="file://$MODULE_DIR$/build/intermediates/assets" />
      <excludeFolder url="file://$MODULE_DIR$/build/intermediates/blame" />
      <excludeFolder url="file://$MODULE_DIR$/build/intermediates/builds" />
      <excludeFolder url="file://$MODULE_DIR$/build/intermediates/classes" />
      <excludeFolder url="file://$MODULE_DIR$/build/intermediates/incremental" />
      <excludeFolder url="file://$MODULE_DIR$/build/intermediates/incremental-classes" />
      <excludeFolder url="file://$MODULE_DIR$/build/intermediates/incremental-runtime-classes" />
      <excludeFolder url="file://$MODULE_DIR$/build/intermediates/incremental-safeguard" />
      <excludeFolder url="file://$MODULE_DIR$/build/intermediates/incremental-verifier" />
      <excludeFolder url="file://$MODULE_DIR$/build/intermediates/instant-run-resources" />
      <excludeFolder url="file://$MODULE_DIR$/build/intermediates/instant-run-support" />
      <excludeFolder url="file://$MODULE_DIR$/build/intermediates/jniLibs" />
      <excludeFolder url="file://$MODULE_DIR$/build/intermediates/manifests" />
      <excludeFolder url="file://$MODULE_DIR$/build/intermediates/multi-dex" />
      <excludeFolder url="file://$MODULE_DIR$/build/intermediates/pre-dexed" />
      <excludeFolder url="file://$MODULE_DIR$/build/intermediates/reload-dex" />
      <excludeFolder url="file://$MODULE_DIR$/build/intermediates/res" />
      <excludeFolder url="file://$MODULE_DIR$/build/intermediates/restart-dex" />
      <excludeFolder url="file://$MODULE_DIR$/build/intermediates/rs" />
      <excludeFolder url="file://$MODULE_DIR$/build/intermediates/shaders" />
      <excludeFolder url="file://$MODULE_DIR$/build/intermediates/split-apk" />
      <excludeFolder url="file://$MODULE_DIR$/build/intermediates/symbols" />
      <excludeFolder url="file://$MODULE_DIR$/build/intermediates/transforms" />
      <excludeFolder url="file://$MODULE_DIR$/build/outputs" />
      <excludeFolder url="file://$MODULE_DIR$/build/tmp" />
    </content>
    <orderEntry type="jdk" jdkName="Android API 25 Platform" jdkType="Android SDK" />
    <orderEntry type="sourceFolder" forTests="false" />
    <orderEntry type="library" exported="" name="google-http-client-android-1.22.0" level="project" />
    <orderEntry type="library" exported="" name="firebase-analytics-10.2.0" level="project" />
    <orderEntry type="library" exported="" name="firebase-core-10.2.0" level="project" />
    <orderEntry type="library" exported="" name="play-services-auth-base-10.2.0" level="project" />
    <orderEntry type="library" exported="" name="gson-2.8.0" level="project" />
    <orderEntry type="library" exported="" name="play-services-tasks-10.2.0" level="project" />
    <orderEntry type="library" exported="" name="constraint-layout-1.0.2" level="project" />
    <orderEntry type="library" exported="" name="appengine-api-1.0-sdk-1.9.50" level="project" />
    <orderEntry type="library" exported="" name="design-25.3.0" level="project" />
    <orderEntry type="library" exported="" name="android-job-1.1.8" level="project" />
    <orderEntry type="library" exported="" name="transition-25.3.0" level="project" />
    <orderEntry type="library" exported="" name="play-services-base-10.2.0" level="project" />
    <orderEntry type="library" exported="" name="multispinner-0.1.1" level="project" />
    <orderEntry type="library" exported="" name="play-services-auth-10.2.0" level="project" />
    <orderEntry type="library" exported="" name="support-core-ui-25.3.0" level="project" />
    <orderEntry type="library" exported="" name="simpleratingbar-0.1.5" level="project" />
    <orderEntry type="library" exported="" name="play-services-maps-10.2.0" level="project" />
    <orderEntry type="library" exported="" name="play-services-location-10.2.0" level="project" />
    <orderEntry type="library" exported="" name="firebase-iid-10.2.0" level="project" />
    <orderEntry type="library" exported="" name="support-core-utils-25.3.0" level="project" />
    <orderEntry type="library" exported="" name="jsr305-2.0.1" level="project" />
    <orderEntry type="library" exported="" name="support-fragment-25.3.0" level="project" />
    <orderEntry type="library" exported="" scope="TEST" name="multidex-instrumentation-1.0.1" level="project" />
    <orderEntry type="library" exported="" name="constraint-layout-solver-1.0.2" level="project" />
    <orderEntry type="library" exported="" name="androidannotations-api-3.2" level="project" />
    <orderEntry type="library" exported="" name="java-uuid-generator-3.1.4" level="project" />
    <orderEntry type="library" exported="" name="google-http-client-1.22.0" level="project" />
    <orderEntry type="library" exported="" name="firebase-messaging-10.2.0" level="project" />
    <orderEntry type="library" exported="" name="firebase-analytics-impl-10.2.0" level="project" />
    <orderEntry type="library" exported="" name="firebase-common-10.2.0" level="project" />
    <orderEntry type="library" exported="" name="eventbus-3.0.0" level="project" />
    <orderEntry type="library" exported="" name="cat-1.0.5" level="project" />
    <orderEntry type="library" exported="" name="play-services-basement-10.2.0" level="project" />
    <orderEntry type="library" exported="" name="support-compat-25.3.0" level="project" />
    <orderEntry type="library" exported="" name="support-v4-25.3.0" level="project" />
    <orderEntry type="library" exported="" name="multidex-1.0.1" level="project" />
    <orderEntry type="library" exported="" scope="TEST" name="hamcrest-core-1.3" level="project" />
    <orderEntry type="library" exported="" name="support-media-compat-25.3.0" level="project" />
    <orderEntry type="library" exported="" scope="TEST" name="junit-4.12" level="project" />
    <orderEntry type="library" exported="" name="recyclerview-v7-25.3.0" level="project" />
    <orderEntry type="library" exported="" name="appcompat-v7-25.3.0" level="project" />
    <orderEntry type="library" exported="" name="animated-vector-drawable-25.3.0" level="project" />
    <orderEntry type="library" exported="" name="support-annotations-25.3.0" level="project" />
    <orderEntry type="library" exported="" name="support-vector-drawable-25.3.0" level="project" />
    <orderEntry type="module" module-name="backend" exported="" />
    <orderEntry type="library" exported="" name="android-android-25" level="project" />
  </component>
</module>

IntelliJ IDEA creates a project for the entire code base you work with, and a module for each of its individual components. So, IntelliJ IDEA module is more like an Eclipse project, and project is roughly similar to Eclipse workspace. There's no exact equivalent to Eclipse's workspace that contains all your work, but you can open multiple projects in multiple frames at the same time.

Here is the IntelliJ IDEA Q&A for Eclipse Users page-

http://www.jetbrains.com/idea/documentation/migration_faq.html

Modules are like apkLibs ie it has its own res, manifest, tests etc but the main app usually uses various apklibs/modules to help put it all together in one solution