use a !# script maker instead, avoid the term "portable"

Author: KristofferC

base/client.jl

@@ -277,7 +277,7 @@ function exec_options(opts)
 
     if arg_is_program && PROGRAM_FILE != "-" && Base.active_project(false) === nothing
         script_path = abspath(PROGRAM_FILE)
-        Base.has_inline_project(script_path) && Base.set_active_project(script_path)
+        Base.is_script(script_path) && Base.set_active_project(script_path)
     end
 
     # Load Distributed module only if any of the Distributed options have been specified.
@@ -347,12 +347,12 @@ function exec_options(opts)
                 include_string(Main, read(stdin, String), "stdin")
             else
                 abs_script_path = abspath(PROGRAM_FILE)
-                if has_inline_project(abs_script_path)
-                    set_portable_script_state(abs_script_path)
+                if is_script(abs_script_path)
+                    set_script_state(abs_script_path)
                     try
                         include(Main, PROGRAM_FILE)
                     finally
-                        global portable_script_state_global = nothing
+                        global script_state_global = nothing
                     end
                 else
                     include(Main, PROGRAM_FILE)

base/initdefs.jl

@@ -288,8 +288,8 @@ function load_path_expand(env::AbstractString)::Union{String, Nothing}
             program_file = program_file != C_NULL ? unsafe_string(program_file) : nothing
             isnothing(program_file) && return nothing # User did not pass a script
 
-            # Check if the program file itself is a portable script first
-            if env == "@script" && Base.has_inline_project(program_file)
+            # Check if the program file itself is a script first
+            if env == "@script" && Base.is_script(program_file)
                 return abspath(program_file)
             end
 
@@ -333,7 +333,7 @@ load_path_expand(::Nothing) = nothing
     active_project()
 
 Return the path of the active project (either a `Project.toml` file or a julia
-file when using a [portable script](@ref portable-scripts)).
+file when using a [script](@ref scripts)).
 See also [`Base.set_active_project`](@ref).
 """
 function active_project(search_load_path::Bool=true)
@@ -364,7 +364,7 @@ end
     set_active_project(projfile::Union{AbstractString,Nothing})
 
 Set the active `Project.toml` file to `projfile`. The `projfile` can be a path to a traditional
-`Project.toml` file, a [portable script](@ref portable-scripts) with inline metadata, or `nothing`
+`Project.toml` file, a [script](@ref scripts) with inline metadata, or `nothing`
 to clear the active project. See also [`Base.active_project`](@ref).
 
 !!! compat "Julia 1.8"
@@ -386,7 +386,7 @@ end
     active_manifest(project_file::AbstractString)
 
 Return the path of the active manifest file, or the manifest file that would be used for a given `project_file`.
-When a [portable script](@ref portable-scripts) is active, this returns the script path itself.
+When a [script](@ref scripts) is active, this returns the script path itself.
 
 In a stacked environment (where multiple environments exist in the load path), this returns the manifest
 file for the primary (active) environment only, not the manifests from other environments in the stack.

base/loading.jl

@@ -261,49 +261,37 @@ function extract_inline_section(path::String, type::Symbol)
     # Read all lines
     lines = readlines(path)
 
-    # For manifest, read backwards by reversing the lines
     if type === :manifest
-        lines = reverse(lines)
-        start_marker = "#!manifest end"
-        end_marker = "#!manifest begin"
+        start_marker = "#!manifest begin"
+        end_marker = "#!manifest end"
         section_name = "manifest"
-        position_error = "must come last"
     else
         start_marker = "#!project begin"
         end_marker = "#!project end"
         section_name = "project"
-        position_error = "must come first"
     end
 
     state = :none
-    at_start = true
     content_lines = String[]
+    project_line = nothing
+    manifest_line = nothing
 
     for (lineno, line) in enumerate(lines)
         stripped = lstrip(line)
 
-        # Skip empty lines and comments (including shebang) before content
-        if at_start && (isempty(stripped) || startswith(stripped, '#'))
-            if startswith(stripped, start_marker)
-                state = :reading
-                at_start = false
-                continue
-            end
-            continue
+        # Track positions of sections for validation
+        if startswith(stripped, "#!project begin")
+            project_line = lineno
+        elseif startswith(stripped, "#!manifest begin")
+            manifest_line = lineno
         end
 
-        # Found start marker after content - error
+        # Found start marker
         if startswith(stripped, start_marker)
-            if !at_start
-                error("#!$section_name section $position_error in $path")
-            end
             state = :reading
-            at_start = false
             continue
         end
 
-        at_start = false
-
         # Found end marker
         if startswith(stripped, end_marker) && state === :reading
             state = :done
@@ -321,9 +309,9 @@ function extract_inline_section(path::String, type::Symbol)
         end
     end
 
-    # For manifest, reverse the content back to original order
-    if type === :manifest && !isempty(content_lines)
-        content_lines = reverse(content_lines)
+    # Validate that project comes before manifest
+    if project_line !== nothing && manifest_line !== nothing && project_line > manifest_line
+        error("#!manifest section must come after #!project section in $path")
     end
 
     if state === :done
@@ -335,32 +323,36 @@ function extract_inline_section(path::String, type::Symbol)
     end
 end
 
-function has_inline_project(path::String)::Bool
+function is_script(path::String)::Bool
     for line in eachline(path)
         stripped = lstrip(line)
-        if startswith(stripped, "#!project begin")
+        # Only whitespace and comments allowed before #!script
+        if !isempty(stripped) && !startswith(stripped, '#')
+            return false
+        end
+        if startswith(stripped, "#!script")
             return true
         end
     end
     return false
 end
 
 
-struct PortableScriptState
+struct ScriptState
     path::String
     pkg::PkgId
 end
 
-portable_script_state_global::Union{PortableScriptState, Nothing} = nothing
+script_state_global::Union{ScriptState, Nothing} = nothing
 
-function set_portable_script_state(abs_path::Union{Nothing, String})
+function set_script_state(abs_path::Union{Nothing, String})
     pkg = project_file_name_uuid(abs_path, splitext(basename(abs_path))[1])
 
     # Verify the project and manifest delimiters:
     parsed_toml(abs_path)
     parsed_toml(abs_path; manifest=true)
 
-    global portable_script_state_global = PortableScriptState(abs_path, pkg)
+    global script_state_global = ScriptState(abs_path, pkg)
 end
 
 
@@ -393,7 +385,7 @@ function parsed_toml(toml_file::AbstractString, toml_cache::TOMLCache, toml_lock
                      manifest::Bool=false, project::Bool=!manifest)
     manifest && project && throw(ArgumentError("cannot request both project and manifest TOML"))
     lock(toml_lock) do
-        # Portable script?
+        # Script?
         if endswith(toml_file, ".jl") && isfile_casesensitive(toml_file)
             kind = manifest ? :manifest : :project
             cache_key = "$(toml_file)::$(kind)"
@@ -459,8 +451,8 @@ Same as [`Base.identify_package`](@ref) except that the path to the environment
 is also returned, except when the identity is not identified.
 """
 function identify_package_env(where::Module, name::String)
-    if where === Main && portable_script_state_global !== nothing
-        return identify_package_env(portable_script_state_global.pkg, name)
+    if where === Main && script_state_global !== nothing
+        return identify_package_env(script_state_global.pkg, name)
     end
     return identify_package_env(PkgId(where), name)
 end
@@ -788,7 +780,11 @@ function env_project_file(env::String)::Union{Bool,String}
     elseif basename(env) in project_names && isfile_casesensitive(env)
         project_file = env
     elseif endswith(env, ".jl") && isfile_casesensitive(env)
-        project_file = has_inline_project(env) ? env : false
+        if is_script(env)
+            project_file = env
+        else
+            error("$env is missing #!script marker)")
+        end
     else
         project_file = false
     end
@@ -1046,7 +1042,7 @@ function project_file_manifest_path(project_file::String)::Union{Nothing,String}
         end
     end
     if manifest_path === nothing && endswith(project_file, ".jl") && has_file
-        # portable script: manifest is the same file as the project file
+        # script: manifest is the same file as the project file
         manifest_path = project_file
     end
     if manifest_path === nothing

doc/src/manual/code-loading.md

@@ -397,11 +397,17 @@ are stored in the manifest file in the section for that package. The dependency
 a package are the same as for its "parent" except that the listed triggers are also considered as
 dependencies.
 
-### [Portable scripts](@id portable-scripts)
+### [Scripts](@id scripts)
 
-Julia also understands *portable scripts*: scripts that embed their own `Project.toml` (and optionally `Manifest.toml`) so they can be executed as self-contained environments. To do this, place TOML data inside comment fences named `#!project` and `#!manifest`:
+Julia also understands *scripts* that can embed their own `Project.toml` (and optionally `Manifest.toml`) so they can be executed as self-contained environments. A script is identified by a `#!script` marker at the top of the file (only whitespace and comments may appear before it). The embedded project and manifest data are placed inside comment fences named `#!project` and `#!manifest`:
 
 ```julia
+#!/usr/bin/env julia
+#!script
+
+using Markdown
+println(md"# Hello, single-file world!")
+
 #!project begin
 # name = "HelloApp"
 # uuid = "9c5fa7d8-7220-48e8-b2f7-0042191c5f6d"
@@ -410,9 +416,6 @@ Julia also understands *portable scripts*: scripts that embed their own `Project
 # Markdown = "d6f4376e-aef5-505a-96c1-9c027394607a"
 #!project end
 
-using Markdown
-println(md"# Hello, single-file world!")
-
 #!manifest begin
 # [[deps]]
 # name = "Markdown"
@@ -421,9 +424,9 @@ println(md"# Hello, single-file world!")
 #!manifest end
 ```
 
-Lines inside the fenced blocks should be commented with `#` (as in the example) or be plain TOML lines. The `#!project` section must come first in the file (after an optional shebang and empty lines). If a `#!manifest` section is present, it must come after the `#!project` section, and no Julia code is allowed after the `#!manifest end` delimiter.
+Lines inside the fenced blocks should be commented with `#` (as in the example) or be plain TOML lines. The `#!script` marker must appear at the top of the file, with only whitespace and comments (including an optional shebang) allowed before it. The `#!project` and `#!manifest` sections can appear anywhere in the file (by convention at the bottom), but `#!project` must come before `#!manifest` if both are present.
 
-Running `julia hello.jl` automatically activates the embedded project. The script path becomes the active project entry in `LOAD_PATH`, so package loading works exactly as if `Project.toml` and `Manifest.toml` lived next to the script. The `--project=@script` flag also expands to the script itself when no on-disk project exists but inline metadata is present.
+Running `julia hello.jl` automatically activates the embedded project if the file contains a `#!script` marker. The dependency loading rules for such a script is the same as for a package with the same project and manifest file. The `--project=@script` flag also expands to the script itself if the `#!script` marker is present. Using `--project=script.jl` explicitly requires that the script contains the `#!script` marker.
 
 ### [Workspaces](@id workspaces)
 

test/loading.jl

@@ -1871,40 +1871,37 @@ module M58272_to end
 @eval M58272_to import ..M58272_1: M58272_2.y, x
 @test @eval M58272_to x === 1
 
-@testset "Portable scripts" begin
+@testset "Scripts" begin
     # Test with line-by-line comment syntax and path dependencies
-    portable_script = joinpath(@__DIR__, "project", "portable", "portable_script.jl")
-    output = read(`$(Base.julia_cmd()) --startup-file=no $portable_script`, String)
+    script = joinpath(@__DIR__, "project", "scripts", "script.jl")
+    output = read(`$(Base.julia_cmd()) --startup-file=no $script`, String)
 
-    @test occursin("Active project: $portable_script", output)
-    @test occursin("Active manifest: $portable_script", output)
+    @test occursin("Active project: $script", output)
+    @test occursin("Active manifest: $script", output)
     @test occursin("✓ Random (stdlib) loaded successfully", output)
     @test occursin("✓ Rot13 (path dependency) loaded successfully", output)
     @test occursin("✓ Rot13 methods available", output)
-    @test occursin("Test Summary:", output)
-    @test occursin("Portable Script Tests", output)
-    @test occursin("Pass", output)
 
     # Test with custom manifest= entry in project section
-    portable_script_cm = joinpath(@__DIR__, "project", "portable", "portable_script_custom_manifest.jl")
-    output_cm = read(`$(Base.julia_cmd()) --startup-file=no $portable_script_cm`, String)
-    expected_cm = joinpath(@__DIR__, "project", "portable", "portable_script_custom.toml")
+    script_cm = joinpath(@__DIR__, "project", "scripts", "script_custom_manifest.jl")
+    output_cm = read(`$(Base.julia_cmd()) --startup-file=no $script_cm`, String)
+    expected_cm = joinpath(@__DIR__, "project", "scripts", "script_custom.toml")
 
-    @test occursin("Active project: $portable_script_cm", output_cm)
+    @test occursin("Active project: $script_cm", output_cm)
     @test occursin("Active manifest: $expected_cm", output_cm)
     @test occursin("✓ Custom manifest file is being used: $expected_cm", output_cm)
     @test occursin("✓ Random.rand()", output_cm)
     @test occursin("✓ All checks passed!", output_cm)
 
-    # Test @script behavior with portable script
+    # Test @script behavior with script
     # When using --project=@script, it should use the script file as the project
-    output_script = read(`$(Base.julia_cmd()) --startup-file=no --project=@script $portable_script`, String)
-    @test occursin("Active project: $portable_script", output_script)
-    @test occursin("Active manifest: $portable_script", output_script)
+    output_script = read(`$(Base.julia_cmd()) --startup-file=no --project=@script $script`, String)
+    @test occursin("Active project: $script", output_script)
+    @test occursin("Active manifest: $script", output_script)
     @test occursin("✓ Random (stdlib) loaded successfully", output_script)
 
-    # Test that regular Julia files (without inline sections) work fine as projects
-    regular_script = joinpath(@__DIR__, "project", "portable", "regular_script.jl")
+    # Test that regular Julia files (without #!script) can be set as active project
+    regular_script = joinpath(@__DIR__, "project", "scripts", "regular_script.jl")
 
     # Running the script with --project= should set it as active project
     output = read(`$(Base.julia_cmd()) --startup-file=no --project=$regular_script $regular_script`, String)
@@ -1918,37 +1915,40 @@ module M58272_to end
     @test occursin("Hello from regular script", output)
     @test occursin("x = 42", output)
 
-    portable_script_missing = joinpath(@__DIR__, "project", "portable", "portable_script_missing_dep.jl")
+    script_missing = joinpath(@__DIR__, "project", "scripts", "script_missing_dep.jl")
     err_output = IOBuffer()
-    result = run(pipeline(ignorestatus(`$(Base.julia_cmd()) --startup-file=no $portable_script_missing`), stderr=err_output))
+    result = run(pipeline(ignorestatus(`$(Base.julia_cmd()) --startup-file=no $script_missing`), stderr=err_output))
     @test !success(result)
     @test occursin("Package Rot13 not found in current path", String(take!(err_output)))
 
-    # Test 1: Project section not first (has code before it)
-    invalid_project_not_first = joinpath(@__DIR__, "project", "portable", "invalid_project_not_first.jl")
-    err_output = IOBuffer()
-    result = run(pipeline(ignorestatus(`$(Base.julia_cmd()) --startup-file=no $invalid_project_not_first`), stderr=err_output))
-    @test !success(result)
-    @test occursin("#!project section must come first", String(take!(err_output)))
+    # Test 1: #!script marker not at top (has code before it) - runs as regular script
+    invalid_project_not_first = joinpath(@__DIR__, "project", "scripts", "invalid_project_not_first.jl")
+    result = run(pipeline(ignorestatus(`$(Base.julia_cmd()) --startup-file=no $invalid_project_not_first`)))
+    @test success(result)
 
-    # Test 2: Manifest section not last (has code after it)
-    invalid_manifest_not_last = joinpath(@__DIR__, "project", "portable", "invalid_manifest_not_last.jl")
+    # Test 2: Manifest section before project section - should error when parsed
+    invalid_manifest_not_last = joinpath(@__DIR__, "project", "scripts", "invalid_manifest_not_last.jl")
     err_output = IOBuffer()
     result = run(pipeline(ignorestatus(`$(Base.julia_cmd()) --startup-file=no $invalid_manifest_not_last`), stderr=err_output))
     @test !success(result)
-    @test occursin("#!manifest section must come last", String(take!(err_output)))
+    @test occursin("#!manifest section must come after #!project section", String(take!(err_output)))
 
-    # Test 3: Project not first, but manifest present
-    invalid_both = joinpath(@__DIR__, "project", "portable", "invalid_both.jl")
+    # Test 3: Code before #!script marker with --project - should error
+    invalid_both = joinpath(@__DIR__, "project", "scripts", "invalid_both.jl")
     err_output = IOBuffer()
     result = run(pipeline(ignorestatus(`$(Base.julia_cmd()) --startup-file=no --project=$invalid_both -e "using Test"`), stderr=err_output))
     @test !success(result)
-    @test occursin("#!project section must come first", String(take!(err_output)))
+    @test occursin("is missing #!script marker", String(take!(err_output)))
+
+    # Test 4: Code between sections is now valid
+    valid_code_between = joinpath(@__DIR__, "project", "scripts", "valid_code_between.jl")
+    result = run(pipeline(ignorestatus(`$(Base.julia_cmd()) --startup-file=no $valid_code_between`)))
+    @test success(result)
 
-    # Test 4: Manifest with code in between sections
-    invalid_code_between = joinpath(@__DIR__, "project", "portable", "invalid_code_between.jl")
+    # Test 5: Using --project on a non-script file errors when loading packages
+    regular_script = joinpath(@__DIR__, "project", "scripts", "regular_script.jl")
     err_output = IOBuffer()
-    result = run(pipeline(ignorestatus(`$(Base.julia_cmd()) --startup-file=no --project=$invalid_code_between -e "using Test"`), stderr=err_output))
+    result = run(pipeline(ignorestatus(`$(Base.julia_cmd()) --startup-file=no --project=$regular_script -e "using Test"`), stderr=err_output))
     @test !success(result)
-    @test occursin("#!manifest section must come last", String(take!(err_output)))
+    @test occursin("is missing #!script marker", String(take!(err_output)))
 end

test/project/portable/invalid_both.jl renamed to test/project/scripts/invalid_both.jl

@@ -2,6 +2,8 @@ function foo()
     return 42
 end
 
+#!script
+
 #!project begin
 #!project end