Clone Repo và Mở Project KMP Lần Đầu

Mục Tiêu Bài Học

Sau bài này bạn có:

• GitHub account đã access được private course repository,
• Course codebase đã clone vào một workspace cố định,
• Android Studio đang mở đúng project root,
• Hiểu Gradle sync đầu tiên làm gì với một project Kotlin Multiplatform.

Trước Khi Clone

Cần đảm bảo ba điều:

• GitHub access: bạn có account và thấy private repository.
• Git authentication: máy của bạn clone được code từ GitHub.
• Project root: Android Studio mở đúng root folder của repo.

Tài liệu official:

• Tạo tài khoản GitHub
• GitHub CLI

Phần 1: Xác Nhận GitHub Access Trong Browser

Mở link course invite trong browser trước và kiểm tra:

1. Bạn đăng nhập đúng GitHub account đã dùng khi mua khóa học.
2. Repository page mở được, không trả về 404.
3. Bạn thấy nút xanh Code hoặc clone URL.

Phần 2: Chọn Cách Authenticate

Cài GitHub CLI để khỏi phải copy-paste personal access token vào terminal. Sau đó chạy:

gh --version
gh auth login
gh auth status

Làm theo browser login flow. Khi gh auth status báo bạn đã login đúng account, máy đã có đường authenticate sạch.

Đừng paste personal access token vào notes, screenshots, Discord, support messages hoặc shell history.

Phần 3: Tạo Workspace Cố Định

Đặt repo ở một nơi bạn sẽ giữ suốt khóa học, không phải folder download ngẫu nhiên:

mkdir -p ~/Desktop/kotlin/dan-tech-academy
cd ~/Desktop/kotlin/dan-tech-academy
git clone <course-repo-url>

Dùng đúng private repository URL mà bạn được cấp quyền. Nếu clone báo Repository not found, kiểm tra lại browser access. Nếu clone cứ hỏi authentication, hoàn tất gh auth login hoặc credential manager rồi thử lại.

Phần 4: Mở Đúng Root Folder

Repo có nhiều folder và nhiều module. Bạn phải mở repository root, không mở app, feature, core, shared-app hay iosApp.

Root folder có các file như:

settings.gradle.kts
build.gradle.kts
gradlew

Không thấy settings.gradle.kts nghĩa là bạn đang ở sai folder. Mở Android Studio, chọn Open, chọn repo root và để IDE import Gradle project. Chỉ root folder mới cho Gradle biết toàn bộ danh sách module.

Folder iosApp/ chứa Xcode project. Android Studio không dùng nó. Nếu bạn có Mac, đây là project bạn mở bằng Xcode để chạy bản iOS.

Phần 5: Để Gradle Sync Chạy Xong

Tài liệu official: Gradle build lifecycle.

Sync đầu tiên chậm vì Gradle dựng model của project:

• Đọc settings.gradle.kts để biết các module được include.
• Build build-logic/, nơi chứa convention plugin dùng chung cho mọi module.
• Đọc build file của từng module.
• Tải Gradle wrapper, plugins và library dependencies (Kotlin Multiplatform, Android Gradle Plugin, Compose Multiplatform, Koin, Ktor...).
• Dựng index để Android Studio hiểu code trong commonMain, androidMain và iosMain.

Đừng cancel sync chỉ vì progress bar đứng yên. Chờ tới khi có success rõ ràng hoặc error đầu tiên rõ ràng. Stack trace dài thường chỉ có một nguyên nhân thật, nằm gần phía trên.

Định Hướng Nhanh

Bạn chỉ cần bản đồ thô lúc này để biết mỗi folder chứa gì.

Bảng Xử Lý Lỗi

Checkpoint

git status

Bạn hoàn tất bài này khi:

• Android Studio đang mở repository root.
• Gradle sync thành công. Nếu sync fail, bạn đã copy được error đầu tiên và phân loại nó: access, SDK, JDK, network, dependency hay thiếu local config.